Authorization code grant flow

In the authorization code grant flow, Authorization Server provides an authorization code to a client app. The client app exchanges the authorization code for a set of access and refresh tokens by using a client ID and client secret.

In this flow, protected resources that a client app requests belong to an end user (resource owner). The authorization code grant flow offers the greatest security benefits of the three available flows. User agents (browsers or mobile devices) that could expose protected resources to third-parties do not receive access tokens. Instead, they receive an authorization code that on its own does not provide direct access to protected resources. This flow is recommended for confidential client apps, for example: backend servers that can securely store sensitive information.

Use case

Imagine a bookstore API whose resources are book orders that end users manage through an external Book Order Management web app with an underlying backend server. The app needs users’ permissions to post orders on their behalf, modify existing orders, and cancel orders. The authorization code grant flow applies to this scenario because the Book Order Management web app can securely store an access token and a longer-lived refresh token. The Authorization Server passes the tokens directly to the backend server in exchange for the authorization code. The authorization code is the only element ever sent to the browser. Even if a third party intercepts the code, it cannot use the code on its own to manipulate users’ orders.

Response

In the authorization code grant flow, a sample Authorization Server JSON response that includes an access token and a refresh token may look like this:

{ 
  "access_token": <token>
  "token_type": "Bearer",
  "expires_in": 1799,
  "refresh_token": "BWefedp0tbWgl7FH6xxG1w",
  "scope": "http://bookstore.api.akamai.com/users/id.write"
}

Process

Here’s a detailed overview of the full OAuth 2.0 process in the authorization code grant flow case:

  1. A resource owner opens the registered client app on their device.
  2. The client app contacts the Authorization Server for an access token.
  3. The Authorization Server asks the resource owner to choose an IdP they want to log in with.
    Note: This can either be a third-party IdP or an IdP you set up to store resource owner details. Akamai does not act as an IdP in the API Gateway context. However, if you’re an Enterprise Application Access (EAA) customer, you may use Akamai as your IdP to enable SAML and single sign-on (SSO) authentication for your applications. For more details, see the EAA product page.
  4. The resource owner logs in with the selected IdP.
  5. The IdP asks the resource owner to grant the Authorization Server permissions to use their credentials.
  6. The resource owner grants the Authorization Server permissions.
    Note: At this stage, the resource owner sees the first consent page that lists the scopes the Authorization Server needs to verify the resource owner’s identity.
  7. The IdP provides an authorization code to the Authorization Server.
  8. The Authorization Server asks the IdP to exchange the authorization code for an access token.
  9. The IdP verifies the authorization code and provides an access token.
  10. The Authorization Server asks the resource owner to grant the client app permissions to use their data.
  11. The resource owner grants the client app permissions to use their data.
    Note: At this stage, the resource owner sees a second consent page that lists the scopes the client app needs to interact with the APIs that contain the resource owner’s data.
  12. The Authorization Server provides an authorization code to the client app.
    Note: The client app receives the authorization code through the user agent that it runs on.
  13. The client app asks the Authorization Server to exchange the authorization code for an access token and refresh token.
  14. The Authorization Server verifies the authorization code and provides an access token and refresh token to the client app.
    Note: The client app receives the tokens through its backend server.
  15. With a valid access token, the client app contacts the resource server again to request the resource owner’s data.
  16. The resource server validates the access token and provides the requested data to the client app.

The client app can make subsequent requests to the resource server until the refresh token received from the Authorization Server expires, in which case the process repeats.