OAuth 2.0 scopes

The purpose of OAuth 2.0 scopes is to limit the access rights granted to an OAuth client through an access token.

The following diagram should explain, how an authorization server decides what scopes to present to a user for consent:

1. The AS supports the following sources for scopes:
• The client requests a set of scopes when starting an authorization code flow or grant.
• In the static client configuration of the AS, a list of Allowed/Default Scopes can be configured. In combination with the Filter Requested Scopes property, this is either interpreted as a filter against client-requested scopes or a default value to override client-supplied scopes.
• During registration using DCR a set of scopes can be registered and stored with the client.
• In the static client configuration of the AS or in the authorization code flow/grant, a list of Always Granted Scopes can be configured. This list is not affected by AS policies or filtering or user local consent choices
2. The AS can be configured with
• a policy that decides how the different sources for scopes are processed.
• a filtering configuration that is applied to the selected source of scopes.
3. In the local consent step of the authentication flow, the user will be presented with a form that
• presents the user with a list of all the scopes the AS has been configured to accept from the different sources after applying policies and filters.
• requires the user to decide whether a scope is granted or denied.
• persists the user's decision regarding the scopes.
• will only be shown again, if there is at least one scope that has not been decided (this may be a new scope or a scope that has been deleted by an administrator).
• will never ask the user for consent on Always Granted Scopes.
4. During the final processing of the authorization code flow/grant, the following steps are executed:
1. the list of Always Granted Scopes is added to the user-consented scopes.
2. Claims are generated and Claim Conditions are applied
3. the Granted Scope Processors configuration is applied to generate the scope claim
4. access, ID, and refresh tokens are issued.

The Scope Policy property is configured for an authorization code flow/grant and applies to all clients (static and dynamic) using it.

• There are 4 scope policies available:
• Scopes Mandatory – 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.

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.

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