Claims Mappers#

The claims engine of Curity includes the concept of a claim mapper. The purpose of a claim mapper is to map claims by name to their usage. This is best explained by the following diagram

The diagram shows that:

• there are default mappings for Access Token, ID Token and UserInfo
• there is a mapping for the custom usage internal_token
• the internal_token is an access token (i.e. its purpose is access_token)

Notice that claims are divided into system claims and custom claims. A system claim is a claim that always exists and has a value that is established by the context, e.g. iat is a system claim that is assigned the issued-at value of the issued token. System claims are predefined for each token purpose and owned by the system; they can not be redefined. By default, a system claim is always included in a token, and as such it can not be requested explicitly. Custom claims on the other hand are claims that are defined by configuration and are never included in a token by default.

When a claim is allowed to be included in a token, the claims mapper will map the allowed claim to the token when the token is issued. This makes the claims mapper act as an output filter of claims, as a claim can never end up in a token that is not the target of a claims mapping.

Use claims mapper usage with claims request parameter#

A claim can be requested for use with a specific token usage through the claims request parameter. For example, if a claim should be issued as part of an internal_token only, the claims parameter can be used like this:

{
    "internal_token": {
        "bank_account": null
    }
}

When this request is satisfied, the bank_account claim will be issued as part of an access token with usage internal_token, but not in any other token. Even when mappings exist for that claim in other token usages.

Use custom claim usage in procedure#

By default the token procedures will issue default tokens. That means that the default mappings are applied to the claims of the issued tokens. If you want to issue non-default tokens, a custom token procedure is required.

The following token procedure would issue two access tokens, one default access token, and one access token of the internal_token usage. Given the previous example, this would result in the internal_token to contain the claim bank_account, whereas the default access token will not contain this claim.

function result(context) {
    var delegationData = context.getDefaultDelegationData()
    var issuedDelegation = context.delegationIssuer.issue(delegationData)

    var accessTokenData = context.getDefaultAccessTokenData()
    var issuedAccessToken = context.accessTokenIssuer.issue(
        accessTokenData,
        issuedDelegation
    )

    // issue a custom access token
    var internalAccessTokenData = context.getDefaultData('internal_token')
    var issuedInternalAccessToken = context.accessTokenIssuer.issue(
        internalAccessTokenData,
        issuedDelegation
    )

    return {
        scope: accessTokenData.scope,
        access_token: issuedAccessToken,
        internal_access_token: issuedInternalAccessToken,
        token_type: 'bearer',
        expires_in: secondsUntil(accessTokenData.exp),
        claims: context.getAccessTokenClaimNames(),
    }
}

Notice that the response will only include a claims response parameter to indicate the claims that were included in the default access token, so in this example the claims response parameter would not have a value (because the custom claim is only included in the custom internal_token access token).

Also note that a claim usage (default or custom) is only available if its purpose is allowed in the procedure’s flow. Namely, usages with the userinfo purpose are only available in procedures in the User Info endpoint. Usages with any other purpose are available to all token procedures.