Grants and flow configuration overview

Overview of the OAuth 2.0 / OIDC Grants Flows and Endpoints

To configure grants and flows for an authorization server, navigate to OAuth 2.0 / OpenID Connect AS Settings >> Authorization Servers >> select the desired AS and create a new OAuth 2.0 Grants / OpenID Connect Flows plugin.

  • The authorization server provides support for:
  • OAuth 2.0 Authorization Code Grant
  • OIDC Authorization Code / Hybrid Flow
  • OAuth 2.0 Client Credentials Grant
  • OAuth 2.0 Token Exchange Grant

Setting up an authorization server that supports OAuth 2.0 and OIDC simultaneously is not supported. The Config Editor will, therefore, report such a configuration as invalid and fail to activate it.

Clients that use the authorization code flow must add the scope openid as defined in the OIDC specification. An OIDC authorization server will return an error if the openid scope is missing.

OAuth 2.0 Authorization Code Grant configuration

To fully configure the OIDC authorization code flow, the following configurations are required:

Configuration

Options

Special properties

Authorization Code

Configuration of the lifetime of authorization codes used during the authorization code flow.

Configuration whether PKCE is enabled (recommended) or not.

Access Token

Configure the content and behavior of the access token.

By default, access tokens are opaque, random strings. If a JWT token should be issued, a JWT Access Token Format plugin may be configured.

Refresh Token

Configure the behavior of refresh tokens. Refresh tokens are always issued as opaque, random strings.

User Interface

Configure the consent property with an OAuth 2.0 Local Consent plugin if users should be involved in reviewing requested scopes and only approve those scopes that they agree with.

Configure the consent property with an OAuth 2.0 Remote Consent plugin if consent management is delegated to an independent consent management service. See OAuth 2.0 scopes and claims.

Configure a scope translator to present scopes in human-readable terms.

Advanced Settings

Supplying a redirect URI with every request to the authorize endpoint is, by definition, optional. It is strongly recommended to make this parameter mandatory for security reasons and to avoid issues with clients that use multiple redirect URIs.

Configure if tokens with an empty scope are issued at all. It is strongly recommended to force clients to request at least one scope.

For OAuth 2.0 the openid scope must not be used.

Configure which scopes are permitted to be added when tokens are issued.

This processor is applied after the user grants consent. As a consequence, a scope granted by the user during consent may not be added to the access token.

OIDC Authorization Code / Hybrid Flow configuration

To fully configure the OIDC authorization code flow or hybrid flow, the following configurations are required:

Configuration

Options

Special properties

Authorization Code

Configuration of the lifetime of authorization codes used during the authorization code flow.

Configuration whether PKCE is enabled (recommended) or not.

Access Token

Configure the content and behavior of the access token.

By default, access tokens are opaque, random strings. If a JWT token should be issued, a JWT Access Token Format plugin may be configured.

Refresh Token

Configure the behavior of refresh tokens. Refresh tokens are always issued as opaque, random strings.

ID Token

Configure the content and behavior of the identity token.

ID tokens are always JWTs. Use this plugin to configure the claims to be included in the ID token.

ID token claims are limited to user context data items.

During the issuance of an ID token, it is possible to convert acquired roles to ACR values.

Hybrid Flow

Used to enable the hybrid flow feature. It configures whether a hybrid flow is allowed and whether an ID token and/or access token may be requested. It also defines the properties of the issued tokens.

User Interface

Configure the consent property with an OAuth 2.0 Local Consent plugin if users should be involved in reviewing requested scopes and only approve those scopes that they agree with.

Configure the consent property with an OAuth 2.0 Remote Consent plugin if consent management is delegated to an independent consent management service. See OAuth 2.0 scopes and claims.

Configure a scope translator to present scopes in human-readable terms.

Flow Settings

The flow settings define how the configured OIDC flow is connected to and used with authentication flows.

Configure the login hint.

  • Configuring the OpenID Connect Username Login Hint plugin will allow the client to supply a username in the authorize call. This username will be pre-filled on the login screen.
  • Configuring an OpenID Connect SSO Ticket Login Hint will allow the client to supply an SSO ticket in the authorize call. The SSO ticket may be used to authenticate the user.

See the use case example for more information on using SSO tickets with OIDC: Forced user re-authenticate

Advanced Settings

Various advanced settings affect scopes and how information may or may not be represented in responses form the AS.

The Response Modes property restricts the allowed response modes in this flow: defines whether tokens may be returned as fragments, query parameters, or form post parameters.

Client Credentials Grant configuration

To configure the client credentials grant, navigate to OAuth 2.0 / OpenID Connect AS Settings >> Authorization Servers >> OAuth 2.0/OIDC Authorization Server >> OAuth 2.0 Grants/OIDC Flows and create a Client Credentials Grant plugin:

Configuration

Options

Special properties

Access Token Validity

The validity period of access tokens must be configured.

The client credentials grant will only provide access tokens.

Refresh tokens may be enabled for dynamically registered clients only.

Granted Scope Processors

An optional scope processor will limit the scopes a client may obtain as follows:

  • A client may request a list of scopes.
  • If this configuration is omitted, the access token will contain all scopes requested.
  • These optional processors will validate the scopes. Only scopes granted by all processors will be added to the access token.

Signature

A token signature must be configured to protect access tokens against tampering.

Token Exchange Grant configuration

To configure the client credentials grant, navigate to OAuth 2.0 / OpenID Connect AS Settings >> Authorization Servers >> OAuth 2.0/OIDC Authorization Server >> OAuth 2.0 Grants/OIDC Flows and create a OAuth 2.0 Token Exchange plugin:

Configuration

Options

Special properties

Subject Token Validation

Configures the validation of the token the client supplied in the token exchange request.

It is not possible to configure token introspection.

Token Exchange Rules

Configures the token's content and signature returned to the client in the token exchange response.