Scope configuration with flows

Airlock IAM offers solutions for complex scope-related requirements, including applying a scope policy to multiple clients. Moreover, custom claims can be added and applied using conditional rules.

If configured, the Scope Policy property defines how the requested scopes are processed before scope consent or scope filtering. The scope policy can be configured separately for each grant type supported by Airlock IAM.

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:

In addition to the scope policy, the property Allow Issuing Tokens With No Scope can be enabled/disabled. If this option is enabled and the resulting scopes from applying the scope policy result in an empty scope, the request fails.

0. Example 1 (scope filter mode):
1. A statically configured client requests a number of scopes, e.g., firstName, lastName.
2. The client's Allowed/Default Scopes list contains the scopes firstName, lastName, and fullName.
3. Filter Requested Scopes is enabled for the client.
4. The configured Scope Policy is Scopes Mandatory.
5. In this case, the Allowed/Default Scopes list works as an allow list. The requested scopes are filtered against the allowed scopes, leaving the original scopes firstName and lastName untouched.

0. Example 2 (set default scopes mode):
1. A statically configured client requests a number of scopes, e.g., firstName, lastName.
2. The client's Allowed/Default Scopes list is configured with the scopes firstName, lastName, and fullName.
3. Filter Requested Scopes is enabled or disabled for the client.
4. The configured Scope Policy is Always Overwrite Scopes.
5. In this case, the requested scopes are ignored and overwritten by the default scopes firstName and lastName, and fullName from the Allowed/Default Scopes list.

See the plugin documentation for an in-depth explanation of each policy for statically configured and clients stored in the database.

Scope filtering is available for OAuth 2.0 Authorization Code Grant and OIDC Authorization Code Flow.

0. Configuration example for OAuth 2.0 Authorization Code Grant and OIDC Authorization Code Flow with scope filtering
1. Go to:
   Loginapp >> OAuth 2.0/OIDC Authorization Servers >> {{AS-Id}} >> OAuth 2.0 Grants/OIDC Flows
2. Go to:
   OAuth 2.0 Authorization Code Grant OR OIDC Authorization Code Flow >> Section Flow Settings
3. Create and edit an OAuth 2.0 Custom Scopes Flow Settings plugin in the Scope Filtering property.
4. Optionally create Flow Condition Based OAuth 2.0 Scope Condition plugins as required.
5. Optionally create Role Based OAuth 2.0 Scope Condition plugins as required.
6. The AS will be able to determine locally which of the requested scopes may be added to the resulting tokens.

In step 3. of the above list, it is possible to configure an OAuth 2.0 Defaults Scopes Flow Settings plugin if scopes should be derived from roles only.

The following example demonstrates how the OAuth 2.0 Custom Scopes Flow Settings plugin can achieve the same effect of scopes derived from user roles.

0. Configuration example of using OAuth 2.0 Custom Scopes Flow Settings with scopes derived from user roles:
1. Create and edit a Role Based OAuth 2.0 Scope Condition plugin.
2. Configure the Scope Matcher property as follows:
• Create and edit an OAuth 2.0 Scope Matcher plugin.
• Configure the Scope Name Pattern as ".*"
3. Configure the Role Provider property as follows:
• Add an All User Roles plugin to the Role Provider list.
4. The Scope Matcher ensures that all requested scopes are tested against the roles retrieved by the Role Provider. If a pair of requested scope and provided role is identical, they are added to the tokens.

0. Configuration example of using OAuth 2.0 Custom Scopes Flow Settings to accept all requested scopes:
1. Create and edit a Flow Condition Based OAuth 2.0 Scope Condition plugin
2. Configure the Scope Matcher property as follows:
• Create and edit an OAuth 2.0 Scope Matcher plugin.
• Configure the Scope Name Pattern as ".*"
3. Configure the Role Condition property as follows:
• Add the Always Selectable plugin to the Role Provider list.
4. The Scope Matcher ensures that all requested scopes are tested and the Always Selectable condition ensures that all scopes are accepted.

• Internal links:
• Conceptual article OAuth 2.0 scopes and claims