OAuth 2.0 claims

Claims are used in tokens to provide information to clients (ID token) and to resources (access token).

The configuration of claims is part of the configuration of the flow or grant that will issue the tokens that contain the claims. This allows for different claims in tokens issued by an authorization code flow or a client credentials grant.

Access tokens will only have claims if they are configured as JWT token and not opaque.

It is useful to differentiate the following types of claims:

  • ID tokens and, to an extent, access tokens may contain a set of claims with a very specific semantic that is defined here: OIDC ID token claims.
  • Custom claims have a business semantic and may be freely added to access and ID tokens. The values of these claims are configurable. A typical set of claims is defined here: OIDC standard claims.
  • Distributed claims are part of the OIDC specification and can be used to add claims where the content is in a remote location, not in the token itself.

Default claims

OAuth 2.0 and OIDC do not specify any claims to be mandatory, but it is very common that the following claims are found in access and ID tokens:

  • sub - reference to the subject of the token
  • aud - describes the intended recipients of the token i.e. the client_id of the client
  • iss - the issuer of the token
  • scope - only provided with access tokens. See OAuth 2.0 scopes for details.
  • acr - authentication context reference

OpenID Connect Core 1.0 defines iss and sub claims as mandatory for ID tokens.

Other, more technical claims about the token's validity, PKCE and other purposes exist. Since these claims are added automatically as needed, they are not discussed in detail here.

Custom claims

Custom claims can be added to access and ID tokens. Typically custom claims include the following claims:

  • context data items
  • client_id,
  • OAuth session_id (Airlock IAM proprietary value to identify the OAuth session.
  • username, user roles
  • HTTP headers
  • Scriptable Step results

Custom claims are collected at the end of the authentication flow and may be stored in a database. During the issuance of tokens, the values used in custom claims are read from this database. This has the following implications:

  • Every token will return identical values as they were stored at the start of the session.
  • Changes in context data items will not be reflected in custom claims until the next time the user authenticates.
  • The userinfo and resource endpoint do not use the persisted data. Context data items requested through these endpoint will return current values.

  • Adding values from value providers and value map providers
  • String Value Provider Custom Claim is a plugin that can be used to write individual values into a custom claim. A typical example is:
    • HTTP Request Value Provider
  • String From Map Value Provider can be used to extract specific keys from a value map and then write the value of this key into a claim. Typical examples are:
    • User Identity Map
    • Authentication Data Map
    • Roles Provider (incl. Tags propagation)
    • Script Execution Result Value Map Provider

Distributed claims

Distributed claims can be useful if large amounts of data should be shared with an access or ID token or if data should be shared that stems from a different authority.

Claim conditions

With the Custom Claims property, custom claims can be added to every token or JSON response after scope policies and scope filtering have been processed. In addition, a Claim Condition can be set to add custom claims conditionally.

  • The available claim conditions are:
  • Required Scopes Claim Condition – this is met when the configured required scopes have been granted.
  • And Claim Condition, Not Claim Condition, Or Claim Condition – these conditions allow logical combinations of conditions. The condition is fulfilled when the logic requirements match the granted scopes/token's claims.
  • The following plugin types offer the conditional claim property:
  • Custom ID token claims, i.e. Custom Claims for the OpenIDConnectClaimsConfiguration plugin.
  • Standard OIDC claims, i.e. Standard Claims for the OpenIDConnectUserInfoEndpointConfig plugin.
  • Custom JWT claims, i.e. Custom Claims for the JwtAccessTokenFormatConfig and OpenIDConnectUserInfoEndpointConfig plugins.
  • OAuth 2.0 Resource Providers, i.e. Resource Providers in the OAuth2ResourceConfig plugin.
  • OAuth 2.0 Token Exchange Custom Claims, i.e. OAuth2TokenExchangeJwtCustomClaimConfig plugin.