OAuth 2.0 Authorization Code Grant
Configures an OAuth 2.0 Authorization Code Grant.
The Authorization Code Grant uses the following endpoints:
- /<loginapp-uri>/oauth2/v3/<as-identifier>/authorize - The Authorize Endpoint
- /<loginapp-uri>/rest/oauth2/authorization-servers/<as-identifier>/token - The Token Endpoint
authorizationCodeExpiresIn) pkceCodeChallengeMethod) Proof Key for Code Exchange by OAuth 2.0 Public Clients (RFC 7636)
It is strongly recommended to use PKCE in setups involving native mobile apps (see the RFC 8252).
PKCE is always performed if the client starts it; however this property defines the minimum challenge hash method necessary and therefore allows to enforce the usage of PKCE.
If PKCE is required, "plain" should only be used if a legacy client doesn't support S256.
The value configured here applies to all clients, however, it's possible to override it in the configuration of each static client.
Background on PKCE:
OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the Authorization Code interception attack. PKCE helps to mitigate this risk through the use of Proof Key for Code Exchange (pronounced "pixy").
This extension utilizes a dynamically created cryptographic random key called "code verifier". A unique code verifier is created for every authorization request, and its transformed value, called "code challenge", is sent to the authorization server to obtain the Authorization Code. The Authorization Code obtained is later sent to the token endpoint with the "code verifier", which allows the server to verify the possession of the "code verifier" before issuing an Access Token.
pushedAuthorizationRequests) Configures the Pushed Authorization Requests (PAR) endpoint.
If configured, IAM will provide an endpoint that allows starting an authentication flow with PAR.
invalidateOldAccessTokensOnRefresh) accessTokenExpiresIn) Time in seconds for which an Access Token is valid.
Security Warning: a very long Access Token validity is not recommended. If long-lasting access is required and acceptable from a security perspective, consider increasing the Refresh Token validity instead.
singleUseAccessTokens) Indicates whether an Access Token is valid only for a single request.
When enabled, any Access Token may only be used once for example in resource requests, authentications using one-shot, or when used as bearer tokens in REST calls.
accessTokenFormat) Defines the format and structure of the issued OAuth 2.0 Access Tokens.
Tokens will be persisted in the token persister regardless of their format and therefore can be revoked at any time. Changing the format will not result in an invalidation of existing tokens.
generateRefreshToken) refreshTokenExpiresIn) Time in seconds for which a Refresh Token is valid.
Security Warning: Only consider a very long Refresh Token validity if this is acceptable from a security perspective.
singleUseRefreshTokens) Indicates whether Refresh Tokens are only valid for a single refresh request.
When enabled, all other Refresh Tokens of the current OAuth 2.0 session will be invalidated on successful refresh. This ensures that the Refresh Token issued during the current refresh is the only valid Refresh Token for this OAuth 2.0 session.
gracePeriod) The time in seconds during which a single use Refresh Token can still be used after completing a successful refresh. Only relevant if 'Single Use Refresh Tokens' is enabled. If a Refresh Token is used to obtain several new token pairs, only the most recent new token pair is valid.
Warning: This option has security impact!
Configuring a grace period weakens the single use property of Refresh Tokens. If a grace period is not strictly necessary, it is not recommended to use this option.
This option may be used if the client can be unreachable so that the refresh response never reaches the client (e.g. mobile apps losing connection). Normally, the Refresh Token is invalidated in this case, leaving the client without valid tokens.
By configuring a grace period, such a client is able to reuse an already used Refresh Token within the configured time (called grace period) as long as the previously issued new tokens have not been used.
flowApplicationId) When left empty, the default authentication flow is started. The Application ID configured here for all clients can be overridden for individual clients in the corresponding client configuration (static clients only).
scopeFiltering) This filtering takes place after processing the requested scopes (using "Scope Policy" and any allowed scopes of the client).
When not configured explicitly, all requested scopes must be covered by a persistent user role or an acquired flow tag.
consent) If configured, enables displaying a consent page to the user to accept or refuse certain requested scopes.
For "Local Consent", all requested scopes allowed by "Scope Filtering" can be granted by the "Consent Step".
For "Remote Consents", the user is redirected to the configured remote consent URL to confirm OAuth 2.0 scopes at a third party.
If nothing is configured, all requested scopes allowed by "Scope Filtering" are automatically granted and no page is displayed.
scopeTranslator) Translator to convert (technical) local scopes to human-readable strings.
This allows for multi-language, user-friendly explanations of the different access rights.
Does not translate remote scopes.
requireRedirectURI) Indicates whether the redirect_uri parameter is mandatory in OAuth 2.0 requests from the client.
Caution: When the redirect_uri is not mandatory, only clients having exactly one registered redirect_uri will be able to login, otherwise the correct value cannot be determined.
scopePolicy) The scope policy defines how the requested scopes are validated and processed (before they are used for scope consent or scope filtering).
Depending on the selected policy, the following rules apply:
- Scopes Mandatory: It is mandatory for the client to request at least one scope, otherwise the request is denied.
- For static clients for which 'Filter Requested Scopes' is enabled: the requested scopes are filtered against the client's allowed scopes and if the client has no allowed scopes, this is treated as if the client has not requested any scopes at all.
- For static clients for which 'Filter Requested Scopes' is disabled: the requested scopes are not filtered (i.e. all scopes are allowed to be requested).
- For persisted clients, the allowed scopes to request are stored per client and it can be configured there what the effect of an empty list of allowed scopes is.
- Empty Scopes Allowed: It is optional for the client to request scopes.
If scopes are requested:
- For static clients for which 'Filter Requested Scopes' is enabled: the requested scopes are filtered against the client's allowed scopes and if the client has no allowed scopes, this is treated as if the client has not requested any scopes at all.
- For static clients for which 'Filter Requested Scopes' is disabled: the requested scopes are not filtered (i.e. all scopes are allowed to be requested).
- For persisted clients, the allowed scopes to request are stored per client and it can be configured there what the effect of an empty list of allowed scopes is.
- Always Overwrite Scopes: The scopes requested by the client are ignored and replaced by the default scopes of the client. If the client has no default scopes, this is treated as if the client has not requested any scopes at all.
With this policy, the 'Filter Requested Scopes' flag of static clients is ignored. - Empty Scopes Overwritten: When the client does not request any scopes, the request is treated as if the default scopes of this client were requested.
If scopes are requested:
- For static clients for which 'Filter Requested Scopes' is enabled: the requested scopes are filtered against the client's allowed scopes and if the client has no allowed scopes, this is treated as if the client has not requested any scopes at all.
- For static clients for which 'Filter Requested Scopes' is disabled: the requested scopes are not filtered (i.e. all scopes are allowed to be requested).
- For persisted clients, the allowed scopes to request are stored per client and it can be configured there what the effect of an empty list of allowed scopes is.
allowEmptyScope) Indicates if Access / Refresh Tokens and Authorization Codes with no scopes may be issued.
If set to false, no tokens are issued when there are no scopes; instead the authorization server returns an 'access denied' response.
Notice: 'No scopes' can be caused by the client not requesting any scopes, the configured scope policy (especially in combination with 'Filter Requested Scopes' enabled and empty 'Allowed/Default Scopes'), the scope processors or when the user just denies all scopes.
alwaysGrantedScopes) grantedScopeProcessors) Allows to further restrict the granted scopes before issuing the tokens.
The processors will be applied in the configured order and only scopes allowed by all processors may be granted.
If not configured, all granted scopes are assigned to all tokens.
Notice: the scope processors are applied after the configured Scope Policy and thus have no influence on whether the requested scopes are allowed.
type: OAuth2AuthorizationCodeGrant
id: OAuth2AuthorizationCodeGrant-xxxxxx
displayName:
comment:
properties:
accessTokenExpiresIn: 180
accessTokenFormat:
allowEmptyScope: false
alwaysGrantedScopes:
authorizationCodeExpiresIn: 90
consent:
flowApplicationId:
generateRefreshToken: true
gracePeriod:
grantedScopeProcessors:
invalidateOldAccessTokensOnRefresh: false
pkceCodeChallengeMethod: PKCE_NOT_ENFORCED
pushedAuthorizationRequests:
refreshTokenExpiresIn: 900
requireRedirectURI: true
scopeFiltering:
scopePolicy: SCOPES_MANDATORY
scopeTranslator:
singleUseAccessTokens: false
singleUseRefreshTokens: true