Claims

Claims are processed first in the authentication method and then the application registration, where it is possible to decide, which claims are passed to the next step and to do claim transforms and claim tasks.

All claim comparisons are case-sensitive.

The claims process starts in the authentication method when a user authenticates. There it is possible to do claim transforms and claim tasks and configure which claims have to be carried forward to the next step. Then the claims process continues in the application registration where it is also possible do claim transforms and configure which claims have to be issued to the application / API.

In a Client Credentials Grant scenario, the claims process is only done in the application registration. The same goes for the claim transforms and the configuration of which claims have to be issued to the application / API.

For values used within FoxIDs, choose _local: for one transform set, _internal: for the current authentication flow including application transforms, or _session: for later browser logins through the same authentication method. These reserved claims are not issued to applications. See Local, internal and session claims, including how to copy a session value to an internal claim for use by application transforms.

Authentication method

In both an OpenID Connect and SAML 2.0 authentication method claims are carried forward by adding them to the Forward claims list. All claims are carried forward if a wildcard * is added to the Forward claims list.

The following claims identify the last authentication method used. They are forwarded by default and can be read in the application registration and used in claim transforms and claim tasks:

  • auth_method contains the authentication method name, which is unique within the environment.
  • auth_method_type contains the authentication method type: login, oidc, oauth2, saml2, wsfed, env_link or ext_login.
  • auth_profile_method contains the name of the selected authentication method profile. This claim is included when a profile is used.

A sub claim and tokens received from an external Identity Provider are nested with a pipe symbol (|) after the authentication method name. Examples:

  • An external sub with the value afeda2a3-c08b-4bbb-ab77-35138dd2ef2d gets the nested value the-auth-method|afeda2a3-c08b-4bbb-ab77-35138dd2ef2d
  • An external access token with the value eyJhG.cRwczov...nNjb3B.lIjoi is added in the access_token claim with the nested value the-auth-method|eyJhG.cRwczov...nNjb3B.lIjoi
  • If the external OpenID Provider returns a refresh token, it can be forwarded in the refresh_token claim with the nested value the-auth-method|refresh-token-value

Application registration

In both an OpenID Connect, OAuth 2.0 and SAML 2.0 application registration claims are issued to the application / API by adding them to the Issue claims list. All claims are issued to the application / API if a wildcard * is added to the Issue claims list.

An OpenID Connect application registration can differentiate if a claim is only issued in the access token or also in the ID token.

An OpenID Connect and OAuth 2.0 application registration can carry claims forward by a scope as well. This is done by adding the claim or claims to a scope's Voluntary claims list. And the claims are then issued if the client application request for the scope.
An OpenID Connect application registration can also in the voluntary scope claims differentiate if a claim is only issued in the access token or also in the ID token.

Claim value types

JWT claim value types, including JSON objects, arrays, booleans and numbers, are retained when claims are copied by a Map transform or carried through sessions, Extended UI and OAuth grants. OpenID Connect UserInfo returns these values with their corresponding JSON types.

Transforms that produce new text, such as regex mapping and concatenation, produce string values.

JWT/SAML claim mapping preserves value types such as booleans and numbers. When mapping JWT to SAML, JSON values are carried as text in string attributes. When mapping SAML to JWT, string values containing valid JSON objects or arrays become JSON claims.

Impersonated identities

An authentication method can select another user with an Impersonation transform. Application transforms then receive the target user's claims and an act claim identifying the original authenticated user. _impersonate: claims prepare the selection within authentication-method transforms; local helper claims retain their reserved names under this prefix.

In JWTs, act is a JSON object, for example {"sub":"original-user"}. Its default SAML mapping is http://schemas.foxids.com/ws/identity/claims/act, which can be overridden in the environment's claim mappings. Select the mapped claim in the SAML application's Issue claims, or use *, to issue its JSON text. When a SAML attribute containing this JSON text is mapped back to act, FoxIDs issues it as a JSON object in the JWT.

Protected claims

FoxIDs manages claims that control sessions, token validity and authentication-method routing. These protected claims cannot be configured as outputs of claim transforms, used in custom JWT/SAML claim mappings, or supplied with static values.

The protected JWT claim names are:

  • sid, iss, aud, exp, nbf, iat and auth_time.
  • client_id, azp, scope, nonce, at_hash and c_hash.
  • auth_method, auth_method_type, auth_profile_method and auth_method_issuer.

The corresponding SAML session index, authentication instant, client ID and authentication-method claim types are also protected. FoxIDs' built-in protocol mappings remain available.

Transforms can read protected claims and copy their values to custom claims. A protected claim can also be selected in a forward or issue list without supplying static values.

The same restrictions apply to custom claims on internal and external users, initial tenant user claims, Access Structure node claims, dynamic UI output claims, and static application and scope claims.

Protected claims returned by a Claims API, Extended UI validation API, External Login API or Directory Connector API are discarded. Existing protected claims in the flow are retained. Selected protected claims can be sent to these APIs as input.