OAuth 2.0 scopes and claims

The purpose of OAuth 2.0 scopes is to limit the authorization granted by the user to a client.

0. With Airlock IAM as AS, this can be implemented as follows:
1. The client requests a set of scopes when starting an OAuth flow.
2. The AS applies a scope policy. Depending on the scope policy configuration, the policy is used to validate the clients' request scopes.
3. The AS filter removes non-allowed scopes from the client's request.
4. The AS presents the filtered scopes to the user during authentication.
5. The user decides which scopes to grant through local or remote consent.
6. Claims are added to the resulting tokens by the AS scope processor based on the granted scopes.

The Airlock IAM Scope Policy property allows configuring the scope handling per client (for static and persisted clients). Scope policies can remove non-allowed scopes or replace scopes with default scopes. The effect of scope policies on the client's scopes depends on the client type (static or persisted) and configuration, i.e., the list of Allowed/Default Scopes and whether Filter Requested Scopes is enabled or disabled. The property Allow Issuing Tokens With No Scope can be enabled to allow issuing tokens even when applying the scope policy results in an empty scope (by default, the request fails in this case).

The scope policy defines how the requested scopes are validated and processed before they are used for scope consent or filtering. Notice that the mandatory openid scope requested by the client merely acts as a marker and is ignored when applying the policy, i.e., when requesting only the openid scope, the scope policy treats this as a request without scopes.

• There are 4 scope policies available:
• Scopes Mandatory – here, the request must contain at least one scope in addition to the scope openid. Otherwise, the request is denied.
• Empty Scopes Allowed – it is optional for the client to request scopes other than openid.
• Always Overwrite Scopes – the scopes requested by the client are ignored and replaced by the scopes from the Allowed/Default Scopes list. If the client has no default scopes, this is treated as if the client has not requested any scopes.
• Empty Scopes Overwritten – when the client does not request any scopes other than openid, the request is treated as if the scopes from the Allowed/Default Scopes list were requested.

See the IAM plugin documentation for full details of the scope policy configuration.

The scope policies can be configured separately for each grant/flow type:

For configuration examples, see article Scope configuration in IAM flows.

Scopes are presented to the user when granting consent is required. Airlock IAM allows for multi-language, user-friendly explanations of access rights using a scope translator.

0. To support human-readable scopes, two translation mechanisms are provided:
1. Server-side translation, where the translations are configured on the server.
2. Client-side translations where the client will provide the translations. If the Loginapp UI is used, the Loginapp Design Kit can manage the client-side translations.

0. The Loginapp UI displays scopes based on the following rule:
1. Use server-side translated scope (configuration) if present.
2. Use client-side translated scope if present.
3. Use technical scope name.

If scopes change often, server-side translation is preferable because deploying new translations on clients tends to be more costly.

0. Airlock IAM supports several mechanisms to filter scopes:
1. Dynamically registered clients may only request scopes they were registered for. A configuration option defines whether registering clients without scopes means allow all scopes or allow no scopes.
2. The client (static or dynamic) may request any scope if no scopes have been registered.
3. Scopes requested by the client are filtered against
• roles from various sources (user persister, SSO token, etc.).
• flow properties of the current authentication flow.
• scopes may also be altered by Granted Scope Processors (e.g. to meet STET PSD2 requirements) before being presented to the user.
4. After the user has granted scopes, scopes may again be filtered by the AS.

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

• The available claim conditions are:
• Required Scopes Claim Condition – this is fulfilled when the configured required claims have been granted.
• And Claim Condition, Not Claim Condition, Or Claim Condition – these conditions allow logical combinations of claims. 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.

• Internal links:
• Configuration article Scope configuration in IAM flows
• Supported OAuth/OIDC Features