Claim transforms

Each FoxIDs authentication method and application registration handle claims and support claim transformations. This means that two sets of claim transforms can be executed on each user authentication. First executing claim transforms on the authentication method and then claim transforms on the application registration.

Additional subsets of claim transformations can be performed if a user or an external user is created.

If you create a new claim in a claim transform, the claim is send from the authentication method if the claim or * is in the Forward claims list. The application registration receives the claim and issues the claim if the claim or * is in the Issue claims list or alternative if the claim is in a requested scope's Voluntary claims list.

Please see claim transform examples

Enable Log claim trace in the log settings to see the claims before and after transformation in the logs.

Claim transforms can e.g., be configured in a login authentication method.

And likewise claim transforms can e.g., be configured in a OpenID Connect application registration.

Claims are by default represented as JWT claims. If the authentication method or application registration is SAML 2.0 the claims is represented as SAML 2.0 claims.

A claim transform will do one of op to five different actions depending on the particular claim transform type.

Claim transform actions:

• Add claim - add a new claim
• Add claim, if not match - do the add action if the condition does not match
• Replace claim - add a new claim and remove existing claims if one or mere exist
• Replace claim, if not match - do the replace action if the condition does not match
• Remove claim - remove the claims if one or mere exist

The claim transforms is executed in order and the actions is therefore executed in order. This means that it is possible to create a local variable by adding a claim and later in the sequence removing the same claim again.

With the Add claim, if not match actions it is possible to add a claim if another claim or a claim with a value do not exist.

Claim transform types that support all actions:

• Match claim - do the action if the claim type match
• Match claim and value - do the action if the claim type and claim value match
• Regex match - do the action if the claim type match and claim value match the regular expression

Claim transform types that support Add claim and Replace claim and Add claim, if new claim do not exist actions:

• Map - do the action if the claim type match, then map the claim value to a new claim
• Regex map - do the action if the claim type match and claim value match the regular expression group, then map the group value to a new claim

Claim transform types that support Add claim and Replace claim actions:

• Constant - always do the action (add/replace a claim with a constant value)
• Concatenate - do the action if one or more of the claim types match, then concatenate the claim values to a new claim
• External claims API - Call an external API with the selected claims to add/replace claims with external claims
• DK XML privilege to JSON - Converting the DK privilege to JSON.

External claims - API

You can call your own API from FoxIDs with a claim transformation. The API is called with claims and the claims returned form the API can be added with a add or replace action. The API is only called if at least one selected claim exists. You can use * to select and send all claims to your API.

Use case sceneries

• Call your API from an authentication method each time a user is authenticated either in FoxIDs or with an external identity provider. You can then find the user in your database and return a user ID and maybe a customer ID or basically anything of relevance. For example, you can also create the user in your database.
• Call your API from an application registration with the user ID (sub) and query the users' roles in your database. You API would then either return an empty list or a list of role claims or maybe a more complex rights structurer.

Implement API

You need to implement a simple API that FoxIDs calls when the claim transformation is executed.
Please have a look at the sample code.

The API has a base URL and the functionality is divided into folders. Currently, only the claims folder (functionality) for requesting a list of claims is support.

If the base URL for the API is https://somewhere.org/myclaimsstore the URL for the claims folder will be https://somewhere.org/myclaimsstore/claims.

FoxIDs cloud calls your API from the IP address 57.128.60.142.
The outgoing IP address can be changed and more can be added over time.

Request

The API call is secured with HTTP Basic authentication scheme where FoxIDs sends the ID external_claims as the username and the configured secret as the password.

The API is called with HTTP POST and a JSON body.

This is a request JSON body with two input claims:

{
 "claims": [
        {
            "type": "sub",
            "value": "1b1ac05e-5937-4939-a49c-0e84a89662df"
        },
        {
            "type": "email",
            "value": "some@test.org"
        }
    ]
}

Response - Success

On success the API should return HTTP code 200 and a list of claims (the list can be empty).

For example, the user's sub (user ID / username), customer ID and roles:

{
    "claims": [
        {
            "type": "sub",
            "value": "somewhere/external-some@test.org"
        },
        {
            "type": "customer_id",
            "value": "1234abcd"
        },
        {
            "type": "role",
            "value": "admin_access"
        },
        {
            "type": "role",
            "value": "read_access"
        },
        {
            "type": "role",
            "value": "write_access"
        }
    ]
}

Response - Error

The API must return HTTP code 401 (Unauthorized) and an error (required) if the Basic authentication is rejected. Optionally add an error description in errorDescription.

{
    "error": "invalid_api_id_secret",
    "errorDescription": "Invalid API ID or secret"
}

If other errors occur, the API should return HTTP code 500 or another appropriate error code. It is recommended to add a technical error message in to the return body. The error message can then later be found in the FoxIDs logs.

Error messages returned from the API is NOT displayed for the user only logged.

API Sample

The sample ExternalClaimsApiSample show how to implement the API in ASP.NET Core 8.

You can user this Postman collection to call and test the sample with Postman.

Configure

Configure to call your API in a claims transformation in FoxIDs Control Client.

1. Navigate to the Claim Transform section
2. Click Add claim transform
3. Click External claims API
4. Select Add claim or Replace claim
5. Add the selected claims e.g. sub in Select claims
6. Add the base API URL without the claims folder in API URL
7. Add the API secret
8. Click Update

Claim transform examples

Split the name claim into the two claims given_name and family_name

The transformation will split the value in the name claim at the first occurring space and respectively add the given_name and family_name claims, if they do not already exist.
If there are more than one space in the name claim value. New given_name and family_name claims will not be added because they already exist.

Use two Regex map claim transformations.

• Find the family_name claim value with regex ^\S+\s(?<map>\S+)$
• Find the given_name claim value with regex ^(?<map>\S+)\s\S+$

Remove the default added authentication method name from sub

The authentication method name is default added to the sub claim value as a post name divided by a pipe e.g., some-auth-method|my-external-user-id.

You can do a replace claim on the sub claim to remove the default added post value.

The transformation will split the value in the sub claim and replace the claim with a new sub only containing the original ID.

Use a Regex map claim transformation and select the Replace claim action.

Find the ID without the default added post authentication method name with regex ^(nemlogin\|)(?<map>.+)$

You can do the same in a SAML 2.0 authentication method using the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claim instead of the sub claim.