Custom claims

Custom claims is a feature, that allows your product to add its own custom claims to the token issued by KMD Identity.

After the user has authenticated, but before the token comes back to your application, KMD Identity can call your API asking for custom claims to be added to the token. These are then added, and the token is returned to your application.

One reason to use custom claims could be, that the users of your application needs a token containing extra information, that is not part of the identity provider claims. This functionality will allow your API to use the claims from the identity provider to identify the user, create any new claims you desire in the final token, and send them to KMD Identity. They will then be added to the token, so that when the user returns to your application after signing in, your application can extract what it needs from the token.

Requirements

• An API available through the internet
• That your API is able to handle and validate JWT tokens.
• The claims must follow the requirements described further down.

When calling your custom claims endpoint KMD Identity sends a JWT token for validation. This contains the claims from the identity provider and an Audience. If you do not specify the Audience, when contacting KMD Identity to set up custom claims, it will be the ID of your application. For OpenID applications it is the ClientID, for SAML applications it is the Relying Party Identifier.

If the call to the custom claims API fails, or if the response does not meet the requirements, there are two possibilities. The login flow can either fail and the user will not be signed in, or the user can receive the claims described further down under Custom claims errors and sign in. The standard is that the flow will fail. If you want the user to be able to login, despite custom claims failing, you must specify this when contacting KMD Identity.

Requirements for the custom claims response from your API

• The response from CustomClaims endpoint must be in the following JSON format: { "CustomClaimKey1": "CustomClaimValue1", "CustomClaimKey2": "CustomClaimValue2" }

• Key must be string.

• Value must be string or array of strings.

• Must NOT be arrays in arrays.

• Length of Key must not exceed 200 characters.

• Length of Value must not exceed 1000 characters.

• Length of each string element in array must not exceed 1000 characters.

• Number of Key-Value pairs must not exceed 100. Strings in arrays count towards this limit as well. So "CustomClaimKey":["CustomClaimValue1", "CustomClaimValue2", "CustomClaimValue3"] would count as 3 key-value pairs.

• Key may not be an already existing claim in the SAML Assertion from the Identity Provider.

How to get started

Contact KMD Identity and specify:

• Url for the custom claims endpoint.
• Audience to be included in token (optional, not needed if you want to use the ID of your application).
• The ID of the your application, for OpenID applications the ClientID, for SAML applications the Relying Party Identifier.
• If you want your users to sign in despite custom claims failing (optional, if not set it will break login flow)

Custom claims errors

If anything is wrong with the JSON received from the custom claims endpoint, the custom claims will not be added to the token. Instead two other claims will be added.

If call to Service Provider API fails, is unavailable, timeouts, or JSON is malformed, you will receive:

• A custom claim called correlationid
• A custom claim called customclaimserror

If validation of the rules described in: "Requirements for the custom claims response from your API" fail, you will receive:

• A custom claim called correlationid
• A custom claim called customclaimsvalidationerrors with IDs of any rules failing. The ID corresponds to following rules:

ID1001 - One or more of the keys were too long. ID1002 - One or more values were too long. ID1003 - There were more KeyValuePairs than allowed. ID1004 - One or more keys are also part of the IDP claims and therefore not allowed as custom claims. ID1005 - Following keys are forbidden as custom claims due to being reserved by KMD Identity.