When you map an identity provider claim to a custom name, the claim is passed through to id and access tokens during the authentication/authorization flow. You can transform claim values in the tokens using regular expressions, when required.
-
For instance, certain Hexagon clients call APIs that require a sub claim value as username or id (such as jkdoe, jksmith, ksmith, etc).
-
However, while using Integrated Windows Authentication (IWA), the sub claim value is prefixed with the domain name, such as ACME\jkdoe.
For example, Jane K. Doe authenticates using the IWA identity provider logged into the corporate domain as ACME\jkdoe. The resulting sub claim value in the id and access tokens must be transformed to jkdoe.
In such cases, the following regex and backreference transforms the sub claim value to meet the API requirement:
Regular Expression |
Replace With |
---|---|
(\w+)\\(\w+) |
$2 |
Here, (\w+) is used to group multiple tokens together and create a capture group for extracting a backreference.
-
\w - matches any word character (alphanumeric and underscore).
-
+ - matches 1 or more of the preceding tokens.
-
\\ works as an escape character to match a backslash ("\")
So, there are two groups to match:
-
The first being the domain name (ACME), and
-
The second being the username (jkdoe), which needs to be extracted for the sub claim value to transform access tokens.
When the regex replace method is called, $2, it captures the second group in the regular expression (jkdoe) and replaces it with the value. Therefore, all sub claim values under the ACME domain group (such as, ACME\jkdoe, ACME\jksmith, ACME\ksmith) are captured and replaced with their ids to transform the access tokens (as jkdoe, jksmith, ksmith).
If no match is found, no replacement is made. Non-matching claim values are provided as-is without any changes.
While mapping claims make sure that you do the following.
-
For an identity provider with existing mappings, you can select Group, User, or Provide a value. However, to map into sub, you must select Provide a value and the set the value as sub.
-
Use the correct regular expression, which can vary based on the requirement. For instance, the regular expression for users like jk-doe will differ compared to jkdoe.
Now, to modify claim values in Smart API Manager using regex, follow the steps in Map identity provider claims to Smart API Manager claims.
To learn more about regex and backreference, we recommend the following resources:
-
Microsoft documentation for substitutions in Regex - Guide for substituting a numbered-group
-
Regular-Expressions.info quick start guide - Starting point for learning to use regular expressions
regexr.com - Website for testing regular expressions and replacement backreferences