OAuth 2.0 workflow

The OAuth 2.0 support in IBM Security Access Manager 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.

The authorization code workflow diagram involves the following steps:

  1. 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.
  2. The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.
  3. 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.
  4. 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.
  5. 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.

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:

  1. The OAuth client requests an access token by authenticating with the authorization server with its client credentials, and presenting an authorization grant.
  2. The authorization server validates the client credentials and the authorization grant. If valid, the authorization server issues an access token and a refresh token.
  3. The OAuth client makes a protected resource request to the resource server by presenting the access token.
  4. The resource server validates the access token. If the access token is valid, the resource owner serves the request.
  5. 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.
  6. If access token is not valid, the resource server returns an error.
  7. The OAuth client requests a new access token by authenticating with the authorization server with its client credentials, and presenting the refresh token.
  8. The authorization server validates the client credentials and the refresh token, and if valid, issues a new access token and a new 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.

The implicit grant workflow diagram involves the following steps:

  1. 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.
  2. The authorization server authenticates the resource owner through the user agent and establishes whether the resource owner grants or denies the access request.
  3. 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.
  4. 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.
  5. 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.
  6. The user agent runs the script provided by the web server locally, which extracts the access token and passes it to the client.

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:

  1. The resource owner provides the client with its user name and password.
  2. 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.
  3. After the authorization server validates the resource owner credentials and the client credentials, it issues an access token and optionally a refresh token.

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:

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