OIDC Authorization Code / Hybrid Flow
Configures OpenID Connect Authorization Code and optionally Hybrid Flows.
The Authorization Code and Hybrid Flows use 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.
This extension utilizes a dynamically created cryptographic random key called "code verifier". A unique code verifier is created for every authentication 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 OpenID Connect Authorization Code and/or Hybrid Flows with PAR.
invalidateOldAccessTokensOnRefresh) Indicates whether Access Tokens issued together with a Refresh Token should be invalidated when said Refresh Token is used.
Notice that in a Hybrid Flow, the Access Token issued directly via the fragment has no corresponding Refresh Token. Therefore it will never be invalidated when any Refresh Token is used to perform an Access Token refresh.
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 (including Access Tokens issued by a Hybrid Flow) may only be used once for example in resource requests, authentications using one-shot, or when used as bearer tokens in REST calls.
accessTokenFormat) 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) 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) 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 is only relevant if 'Single Use Refresh Tokens' is enabled: time in seconds during which a single use Refresh Token can still be used after completing a successful refresh.
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. If a Refresh Token is used to obtain several new token pairs, only the most recent new token pair is valid.
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).
acrToFlowAppId) When left empty, the configured "Flow Application ID" authentication flow is always started. The mappings 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.
loginHintFlowSettings) login_hint request parameter. If not configured, the parameter is ignored. openIdConnectTokenExpiresIn) idToken) enableHybridFlow) hybridFlowAccessTokenExpiresIn) hybridFlowAccessTokenFormat) Defines the format and structure of the OAuth 2.0 Access Tokens issued in Hybrid Flows.
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.
If not defined, no Hybrid Flow Access Tokens will be issued and requests containing 'token' in the 'response_type' parameter will be denied.
hybridFlowOpenIdConnectTokenExpiresIn) hybridFlowIdToken) Defines the format and structure of the OpenID Connect ID Tokens issued in Hybrid Flows.
If not defined, no Hybrid Flow ID Tokens will be issued and requests containing 'id_token' in the 'response_type' parameter will be denied.
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) The frontend translations apply even if no scope translator is configured.
scopePolicy) The scope policy defines how the requested scopes are validated and processed (before they are used for scope consent or scope 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 if no scope had been requested at all).
Depending on the selected policy, the following rules apply:
- Scopes Mandatory: It is mandatory for the client to request at least one scope in addition to 'openid', 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 other than 'openid'.
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 other than 'openid', 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. Even though the 'openid' scope is required to be present in the authentication request, it will never be present as granted scopes.
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.
responseModes)
type: OpenIdConnectAuthorizationCodeGrant
id: OpenIdConnectAuthorizationCodeGrant-xxxxxx
displayName:
comment:
properties:
accessTokenExpiresIn: 180
accessTokenFormat:
acrToFlowAppId:
allowEmptyScope: false
alwaysGrantedScopes:
authorizationCodeExpiresIn: 90
consent:
enableHybridFlow: false
flowApplicationId:
generateRefreshToken: true
gracePeriod:
grantedScopeProcessors:
hybridFlowAccessTokenExpiresIn: 180
hybridFlowAccessTokenFormat:
hybridFlowIdToken:
hybridFlowOpenIdConnectTokenExpiresIn: 120
idToken:
invalidateOldAccessTokensOnRefresh: false
loginHintFlowSettings:
openIdConnectTokenExpiresIn: 120
pkceCodeChallengeMethod: PKCE_NOT_ENFORCED
pushedAuthorizationRequests:
refreshTokenExpiresIn: 900
responseModes:
scopeFiltering:
scopePolicy: SCOPES_MANDATORY
scopeTranslator:
singleUseAccessTokens: false
singleUseRefreshTokens: true