Working With Claims

Claims are pieces of information asserted by the Identity Server which end up in tokens or the user info endpoint response. If you're not familiar with how claims work, then have a look at this Introduction to Claims article.

To issue claims, the Curity Identity Server must know two things:

• Which claims should end up in which tokens based on the client and requested scopes.
• From where to take values for the claims.

The first point is achieved with claims mappers and can be configured in the Curity Identity Server's admin UI using the Token Designer. The second one needs Claim Value Providers. These providers need to be properly configured to fill the claims values. This tutorial shows how to configure and test providing values to claims using the admin UI.

Demo video

The following video shows how to configure Claim Value Providers.

Configuring Claim Value Providers

To configure Claim Value Providers for a given Token Service profile go to Profiles -> Token Service -> Scopes. The Token Designer page will open. Either add a new claim by clicking on the + button above the claims list or click on the three dots next to the claim you want to edit and select Edit. The Edit Claim popup will appear.

Pick a Claim Value Provider

First select a Claim Value Provider by clicking on the Edit button in the Claims Provider panel. By default, there should at least be a Claim Value Provider of type Account Manager available, the Account Manager Provider.

Select Attributes

Next, choose the attributes from the provider which will be used to create the value of the claim. For an Account Manager Provider these are fields of the user's profile. Depending on the setting of this provider, these fields are either the fields as present in a SCIM representation of that account, or, if enabled, the standard OpenID Connect profile claims (e.g. phoneNumbers in SCIM can be mapped to phone_number in OIDC).

In case of another provider type, the attributes depend on what the provider exposes. A common use case would be to use either Authentication Context Attributes Provider or Authentication Subject Attributes Provider, which expose, respectively, context and subject attributes. To browse these attributes it is convenient to add a Debug Action to the authentication flow and check what is available.

Set Transformation

If only one attribute is selected as the source of value, then very often the transformation is not needed. The value of the attribute will be used as-is for the claim's value. In some situations, though, you might want to perform additional transformation of the value. The transformation is also required if more than one attribute is used as a source. The transformation method is a Javascript function which accepts the attributes object and should return a single value, which will be used as the claim's value. This value can be of a simple type, like string or number, or have a complex form, e.g. an object or a list.

Testing a Claim Value Provider

You can easily test the final value of the claim based on input data, chosen attributes and applied transformation. The testing panel allows you to test the Claim Value Provider settings without the need of running a whole authorization flow.

To open the test panel click on the Run Test button in the upper right corner. You will see two tabs that run tests depending on where the attributes come from:

• Subject - test with this option if you're using an Account Manager Claims Value Provider. This test picks the attributes from a user account registered in the provider's Account Manager.

• Authentication Attributes - test with this option if you're using an Authentication Context Claims Value Provider or Authentication Subject Claims Value Provider.

Subject Attributes

To run a test using attributes from a subject, first enter a username registered in the chosen Account Manager (the one that the Claim Value Provider uses). Attributes of the chosen account will be used as input to the test.

You can choose which scopes should be used for the test. You can leave that option empty. If you choose any scope, then the result will only contain a value if at least one of the selected scopes is associated with the tested claim.

Clients can have overrides for claims mappers. Next, choose a client to take into account potential overrides when running the test.

Note that entering the subject and client is mandatory to run the test.

Click on the Run Test button at the top. You will see the result of running the value provider, both before and after any transformation.

Authentication Attributes

To run a test using attributes from the authentication flow, first enter the JSON object containing subject and context attributes. You can easily acquire this object by attaching a Debug Action to an authentication flow.

The debug action view has a button, which copies the whole attributes JSON object to clipboard. Simply paste it to the input field in the test tab.

You can choose which scopes should be used for the test. You can leave that option empty. If you choose any scope, then the result will only contain a value if at least one of the selected scopes is associated with the tested claim.

Clients can have overrides for claims mappers. Next, choose a client to take into account potential overrides when running the test.

Note that entering the attributes JSON object and client is mandatory to run the test.

Click on the Run Test button at the top. You will see the result of running the value provider, both before and after transformation.

Claims from Custom Data

Claims can also be issued from any data source. The implementing role based security tutorial shows how to issue custom claims from account data, and the implementing custom claims tutorial shows how to retrieve claims from an external data source, such as a custom API or database.

Conclusion

The Token Designer's Edit Claim feature enables a simple configuration of a value provider for claims. The feature also allows you to test the provider, so that administrators have a good certainty of what the resulting claims will look like.