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.
Configuration of scope policy
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:
Grant type | Where to configure | Scope handling |
---|---|---|
OAuth 2.0 Authorization Code Grant | OAuth 2.0 Grants/OIDC Flows >> OAuth 2.0 Authorization Code Grant >> Scope Policy (section Advanced Settings) | The selected policy is applied to the requested scopes before the scope filtering and the consent step for all grant types. |
OAuth 2.0 Client Credentials Grant | OAuth 2.0 Grants/OIDC Flows >> OAuth 2.0 Client Credentials Grant >> Scope Policy | |
OIDC Authorization Code / Hybrid Flow | OAuth 2.0 Grants/OIDC Flows >> OIDC Authorization Code / Hybrid Flow >> Scope Policy (section Advanced Settings) | |
OAuth 2.0 Token Exchange Grant | OAuth 2.0 Grants/OIDC Flows >> OAuth 2.0 Token Exchange Grant >> Token Exchange Rules >> Scope Claim >> Scope Policy | The selected scope policy is applied to the output of the IAM scope processor. |
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.
- Example 1 (scope filter mode):
- A statically configured client requests a number of scopes, e.g.,
firstName
,lastName
. - The client's Allowed/Default Scopes list contains the scopes
firstName
,lastName
, andfullName
. - Filter Requested Scopes is enabled for the client.
- The configured Scope Policy is Scopes Mandatory.
- 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
andlastName
untouched.
- Example 2 (set default scopes mode):
- A statically configured client requests a number of scopes, e.g.,
firstName
,lastName
. - The client's Allowed/Default Scopes list is configured with the scopes
firstName
,lastName
, andfullName
. - Filter Requested Scopes is enabled or disabled for the client.
- The configured Scope Policy is Always Overwrite Scopes.
- In this case, the requested scopes are ignored and overwritten by the default scopes
firstName
andlastName
, andfullName
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.
Configuration of Scope Filtering
Scope filtering is available for OAuth 2.0 Authorization Code Grant and OIDC Authorization Code / Hybrid Flow.
- Configuration example for OAuth 2.0 Authorization Code Grant and OIDC Authorization Code / Hybrid Flow with scope filtering
- Go to:
Loginapp >> OAuth 2.0/OIDC Authorization Servers >> {{AS-Id}} >> OAuth 2.0 Grants/OIDC Flows - Go to:
OAuth 2.0 Authorization Code Grant OR OIDC Authorization Code / Hybrid Flow >> Section Flow Settings - Create and edit an OAuth 2.0 Custom Scopes Flow Settings plugin in the Scope Filtering property.
- Optionally create Flow Condition Based OAuth 2.0 Scope Condition plugins as required.
- Optionally create Role Based OAuth 2.0 Scope Condition plugins as required.
- 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.
- Configuration example of using OAuth 2.0 Custom Scopes Flow Settings with scopes derived from user roles:
- Create and edit a Role Based OAuth 2.0 Scope Condition plugin.
- Configure the Scope Matcher property as follows:
- Create and edit an OAuth 2.0 Scope Matcher plugin.
- Configure the Scope Name Pattern as ".*"
- Configure the Role Provider property as follows:
- Add an All User Roles plugin to the Role Provider list.
- 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.
- Configuration example of using OAuth 2.0 Custom Scopes Flow Settings to accept all requested scopes:
- Create and edit a Flow Condition Based OAuth 2.0 Scope Condition plugin
- Configure the Scope Matcher property as follows:
- Create and edit an OAuth 2.0 Scope Matcher plugin.
- Configure the Scope Name Pattern as ".*"
- Configure the Role Condition property as follows:
- Add the Always Selectable plugin to the Role Provider list.
- The Scope Matcher ensures that all requested scopes are tested and the Always Selectable condition ensures that all scopes are accepted.
Further information and links
- Internal links:
- Conceptual article OAuth 2.0 scopes and claims