Modify claim values via regex - Intergraph Smart API Manager - 5.0 - Help

Intergraph Smart API Manager Help

Language
English
Product
Intergraph Smart API Manager
Search by Category
Help
Smart API Manager Version
5.0

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.

Where do I add the regex values?

In Smart API Manager, you add the Regular Expressions values in Settings. Select the Identity tab, and in the Claims section, enter the regex values in the Regular Expressions box, as shown in the following example that uses Integrated Windows Authentication (IWA).

REG_EXpressions

It is important that the sub claim value matches the existing login name for the user. If they do not match, the default user is used as a template because the system cannot match the incoming username with an existing one.

Another example of regex settings is to account for the following user name, jdoe-GB1\abc123. In this case, the regex setting needs to change to incorporate the full account name, jdoe-GB1\abc1234, so the Regular Expression on the claim has been modified to (\w*\-\w*)\\(\w*).

While mapping claims make sure that you do the following.

Map Sub to sub.

  • 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: