OAuth 2.0 and OIDC workflows

The OAuth 2.0 support in IBM Security Verify Access provides four different ways for an OAuth client to obtain access the protected resource.

OAuth 2.0 workflow

Advanced Access Control supports the following OAuth 2.0 workflows.

Authorization code flow

The authorization code grant type is suitable for OAuth clients that can keep their client credentials confidential when authenticating with the authorization server. For example, a client implemented on a secure server. As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner. It also must be able to receive incoming requests through redirection from the authorization server.

Note: For OIDC, a Relying Party is an OAuth Client, and an OIDC Provider is an OAuth Authorization server. For OIDC, the authorization code flow returns an authorization code to the Relying Party, which can then directly exchange it for an ID token and access token. This mechanism provides the benefit of not exposing any tokens to the browser or end-user. The OpenID Connect Provider also authenticates the Relying Party before exchanging the authorization code for an access token. The authorization code flow is suitable for Relying Parties that can securely maintain a client secret between themselves and the OpenID Connect Provider.

The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.
For OIDC, the scope must include openid. The state parameter must also be included.
The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.
If the resource owner grants access, the OAuth client uses the redirection URI provided earlier to redirect the user agent back to the OAuth client. The redirection URI includes an authorization code and any local state previously provided by the OAuth client.
If this is an OpenID Connect request, then the redirection URI must be present. For Oauth, by contrast, it can be sourced from the client configuration. This requirement exists because OpenID Connect is stricter on request validation.
The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the authorization code received in the previous step. The OAuth client also includes the redirection URI used to obtain the authorization code for verification.
For OIDC, the Relying Party requests an access token and, in addition, an ID token from the OpenID Connect Provider through the token endpoint.
The authorization server validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the authorization server responds back with an access token. If OIDC is configured, an id token is returned.
For OIDC, if the redirection URI is valid, the OpenID Connect Provider responds back with an access token and an ID token.

The authorization server can be the same server as the resource server or a separate entity. A single authorization server can issue access tokens accepted by multiple resource servers.

Authorization code flow with refresh token

The authorization code workflow with refresh token diagram involves the following steps:

The OAuth client requests an access token by authenticating with the authorization server with its client credentials, and presenting an authorization grant.
The authorization server validates the client credentials and the authorization grant. If valid, the authorization server issues an access token and a refresh token.
The OAuth client makes a protected resource request to the resource server by presenting the access token.de
The resource server validates the access token. If the access token is valid, the resource owner serves the request.
Repeat steps 3 and 4 until the access token expires. If the OAuth client knows that the access token has expired, skip to Step 7. Otherwise, the OAuth client makes another protected resource request.
If access token is not valid, the resource server returns an error.
The OAuth client requests a new access token by authenticating with the authorization server with its client credentials, and presenting the refresh token.
The authorization server validates the client credentials and the refresh token, and if valid, issues a new access token and a new refresh token. For OpenID Connect, an ID token is returned in addition to the new access token and refresh token.

Implicit grant flow

The implicit grant type is suitable for clients that are not capable of maintaining their client credentials confidential for authenticating with the authorization server. An example can be in the form of client applications that are in a user agent, typically implemented in a browser using a scripting language such as JavaScript.

As a redirection-based flow, the OAuth client must be able to interact with the user agent of the resource owner, typically a web browser. The OAuth client must also be able to receive incoming requests through redirection from the authorization server.

Note: For OIDC, a Relying Party is an OAuth Client, and an OIDC Provider is an OAuth Authorization server. For OIDC, the implicit flow can be used by Relying Parties with an in-browser scripting language component. The access token and ID token are returned directly to the Relying Party, which may expose them to the end-user and applications that have access to the end-user's browser. The token endpoint is not used and the OpenID Connect Provider does not perform authentication on the Relying Party in this flow. The Relying Party does not have to directly communicate with the OpenID Connect Provider as all interactions can be performed through the browser.

The implicit grant workflow diagram involves the following steps:

The OAuth client initiates the flow by directing the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.
For OIDC, the requested scope must include openid, and the parameters nonce and state must also be included.
The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.
If the resource owner grants access, the authorization server redirects the user agent back to the client using the redirection URI provided earlier. The redirection URI includes the access token in the URI fragment.
For OIDC, the redirection URI includes both the access token and the ID token in the URI fragment.
The user agent follows the redirection instructions by making a request to the web server without the fragment. The user agent retains the fragment information locally.
The web server returns a web page, which is typically an HTML document with an embedded script. The web page accesses the full redirection URI including the fragment retained by the user agent. It can also extract the access token and other parameters contained in the fragment.
For OAuth 2.0, the user agent runs the script provided by the web server locally, which extracts the access token and passes it to the client.
For OIDC, the script extracts both the access token and the ID token. If response_mode=form_post is specified, the OpenID Provider returns a self-posting form.

Note: When the response type includes token or ID token, the parameter response_mode=form_post is set by default. You can use advanced mapping to change or remove this parameter if necessary. However, by default most authorization servers ignore this parameter if they do not support it.

Hybrid flow

OpenID Connect supports a hybrid flow. In the OAuth 2.0 hybrid flow, an authorization code (response_type = code) or an access token (response_type = token) is returned by the authorization endpoint. Some tokens are returned by the authorization endpoint, and others are returned by the token endpoint.

The hybrid flow is similar to authorization code flow in allowing clients to be authenticated, and in supporting refresh tokens. The hybrid flow is similar to implicit grant flow in allowing tokens to be revealed to the user agent.

The hybrid flow supports multiple response_type values.

Table 1. Response type values for each flow
response_type value	Flow
`code`	Authorization Code Flow
`id_token`	Implicit Flow
`id_token token`	Implicit Flow
`code id_token`	Hybrid Flow
`code token`	Hybrid Flow
`code id_token token`	Hybrid Flow

The hybrid flow uses the steps shown in the diagram for authorization code.

The OAuth client initiates the flow when it directs the user agent of the resource owner to the authorization endpoint. The OAuth client includes its client identifier, requested scope, local state, and a redirection URI. The authorization server sends the user agent back to the redirection URI after access is granted or denied.
For OIDC, the scope must include openid. The state parameter must also be included.

For hybrid flow, the response type is more than just code. For example, response_type = code + id_token will result in the return of both an id_token and code in step 3.
The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.
If the resource owner grants access, the OAuth client uses the redirection URI provided earlier to redirect the user agent back to the OAuth client. The redirection URI includes an authorization code and any local state previously provided by the OAuth client.
If this is an OpenID Connect request, then the redirection URI must be present. For OAuth, by contrast, it can be sourced from the client configuration. This requirement exists because OpenID Connect is stricter on request validation.

For hybrid flow, when the authorization code is returned, an id_token and (or) an access token may also be returned.
The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the authorization code received in the previous step. The OAuth client also includes the redirection URI used to obtain the authorization code for verification.
For OIDC, the Relying Party requests an access token and, in addition, an ID token from the OpenID Connect Provider through the token endpoint.
The authorization server validates the client credentials and the authorization code. The server also ensures that the redirection URI received matches the URI used to redirect the client in Step 3. If valid, the authorization server responds back with an access token. If OIDC is configured, an id token is returned.
For OIDC, if the redirection URI is valid, the OpenID Connect Provider responds back with an access token and an ID token.

For more information on the hybrid flow, see http://openid.net/specs/openid-connect-core-1_0.html#HybridFlowSteps.

Resource owner password credentials flow

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client. For example, the resource owner can be a computer operating system of the OAuth client or a highly privileged application.

You can only use this grant type when the OAuth client has obtained the credentials of the resource owner. It is also used to migrate existing clients using direct authentication schemes by converting the stored credentials to an access token.

The resource owner password credentials workflow diagram involves the following steps:

The resource owner provides the client with its user name and password.
The OAuth client requests an access token from the authorization server through the token endpoint. The OAuth client authenticates with its client credentials and includes the credentials received from the resource owner.
After the authorization server validates the resource owner credentials and the client credentials, it issues an access token and optionally a refresh token.
OIDC requests can return, from a request to /authorize, any combination of the following:
- An access token
- An id_token
- A code
If a code is returned, then the following can be returned to /token:
- An access token
- An ID token
- A refresh token, if enabled
If a refresh token is presented to /token, then following are returned:
- An access token
- An ID token
- A refresh token

JWT and SAML bearer grant type flows

The assertion bearer grant types are an extension to the OAuth 2.0 framework. In such flows, a client presents a JWT or SAML assertion to the token endpoint in exchange for tokens. The assertion that is presented must represent the resource owner for whom tokens will be issued to. See RFC 7522 and RFC 7523 for further details.

The assertions must be validated in the pre-token mapping rule. A callout to the STS is one way to validate a presented assertion.

The following diagram describes the steps in the assertion bearer grant type flows:

The client obtains a JWT or SAML assertion from the resource owner.
The client presents the assertion to the authorization server.
The authorization server validates the presented assertion through signature validation, decryption, or both. The issuer and subject are extracted and validated. If the issuer is trusted, tokens are issued to the subject that is captured in the assertion.

Client credentials flow

The client credentials flow is used when the OAuth client requests an access token using only its client credentials. This flow is applicable in one of the following situations:

The OAuth client is requesting access to the protected resources under its control.
The OAuth client is requesting access to a different protected resource, where authorization has been previously arranged with the authorization server.

The client credentials workflow diagram involves the following steps:

The OAuth client requests an access token from the token endpoint by authenticating with its client credentials.
After the authorization server validates the client credentials, it issues an access token.

Device flow

The OAuth device flow is a draft RFC (Currently version 9, see: https://tools.ietf.org/html/draft-ietf-oauth-device-flow-09). The OAuth device flow is intended for use where the OAuth client is unable to provide any input mechanism to the user, and is only able to broadcast information. Such applications would be smart devices which can display (for example, a smart device plugged into a TV) content, but not provide a user-agent. This means the flow of information is one way from the client to the resource owner. There are three endpoints used in this flow, the device_authorize endpoint, a JSON endpoint used by the client to get the initial device and user codes. The user authorize endpoint, where the user visits to authenticate and authorize the client, and the token endpoint, where the client will poll with the device code.

The steps of a device flow are:

The client makes a request to device authorize and receives a device_code, a user_code and a verification_uri.
The client shows the user_code on the screen, along with the verification uri. The client may also choose to show an alternative method of consuming this user_code and verification code, such as a QR code to be scanned by a resource owner with a mobile device.
The client begins polling the token endpoint with the device_code, it will receive errors of 'authorization_pending' or 'slow_down' while it waits for a user to verify the user code.
The user visits the verification uri presenting the user_code. The user will then be prompted to authenticate and consent. After the user has authenticated and consented, asuccess page is shown.
The client, which has been continuing to poll will now receive a bearer token rather than an 'authorization_pending' error.

The following diagram describes the steps in the device flows:

Token Exchange Flow

The Token Exchange grant type is a draft protocol that allows one user to act on behalf of another. One common use case for a Security Token Service (STS) is to allow a resource server A to make calls to a backend service C on behalf of the requesting user B.

Note: An STS is a service capable of validating security tokens provided to it and issuing new security tokens in response, which enables clients to obtain appropriate access credentials for resources in heterogeneous environments or across security domains.

In the request, the "subject_token" represents the identity of the party on behalf of whom the token is being requested while the "actor_token" represents the identity of the party to whom the access rights of the issued token are being delegated.

Impersonation: When principal A impersonates principal B, A is given all the rights that B has within some defined rights context and is indistinguishable from B in that context. In Impersonation request, only "subject_token" is required.
Delegation: With delegation semantics, principal A still has its own identity separate from B, and it is explicitly understood that while B may have delegated some of its rights to A. In a sense, A is an agent for B. In Delegation request, "subject_token" and "actor_token" are both required.

For more information, see https://tools.ietf.org/html/rfc8693.