Access Management 7.2.2

Authorization code grant

Endpoints

The authorization code grant is a two-step interactive process used when the client, for example, a Java application running on a server, requires access to protected resources.

The authorization code grant is the most secure of all the OAuth 2.0 grants for the following reasons:

  • It is a two-step process. The user must authenticate and authorize the client to see the resources and the authorization server must validate the code again before issuing the access token.

  • The authorization server delivers the access token directly to the client, usually over HTTPS. The client secret is never exposed publicly, which protects confidential clients.

OAuth 2.0 authorization code grant flow
Figure 1. OAuth 2.0 authorization code grant flow
Authorization code grant flow explained

  1. The client, usually a web-based service, receives a request to access a protected resource. To access the resources, the client requires authorization from the resource owner.

  2. The client redirects the resource owner’s user-agent to the authorization server.

  3. The authorization server authenticates the resource owner, confirms resource access, and gathers consent if not previously saved.

  4. The authorization server redirects the resource owner’s user agent to the client.

  5. During the redirection process, the authorization server appends an authorization code.

  6. The client receives the authorization code and authenticates to the authorization server to exchange the code for an access token.

    Note that this example assumes a confidential client. Public clients are not required to authenticate.

  7. If the authorization code is valid, the authorization server returns an access token (and a refresh token, if configured) to the client.

  8. The client requests access to the protected resources from the resource server.

  9. The resource server contacts the authorization server to validate the access token.

  10. The authorization server validates the token and responds to the resource server.

  11. If the token is valid, the resource server allows the client to access the protected resources.

Perform the steps in the following procedures to obtain an authorization code and exchange it for an access token:

Obtain an authorization code using a browser

This procedure assumes the following configuration:

  • AM is configured as an OAuth 2.0 authorization server. Ensure that:

    • The code plugin is configured in the Response Type Plugins field.

    • The Authorization Code grant type is configured in the Grant Types field.

    For more information, see Authorization server configuration.

  • A confidential client called myClient is registered in AM with the following configuration:

    • Client secret: forgerock

    • Scopes: write

    • Response Types: code

    • Grant Types: Authorization Code

For more information, see Client registration.

Perform the steps in this procedure to obtain an authorization code using a browser:

  1. The client redirects the resource owner’s user-agent to the authorization server’s authorization endpoint specifying, at least, the following form parameters:

    • client_id=your-client-id

    • response_type=code

    • redirect_uri=your-redirect-id

    For information about the parameters supported by the /oauth2/authorize endpoint, see /oauth2/authorize.

    If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /alpha realm, then use /oauth2/realms/root/realms/alpha/authorize.

    For example:

    https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/authorize \
?client_id=myClient \
&response_type=code \
&scope=write \
&state=abc123 \
&redirect_uri=https://www.example.com:443/callback

    Note that the URL is split and spaces have been added for readability purposes and that the scope and state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

  2. The resource owner authenticates to the authorization server, for example, using the credentials of the demo user. In this case, they log in using the default chain or tree configured for the realm.

    After logging in, the authorization server presents the AM consent screen:

    The OAuth 2.0 AM user interface consent screen requesting access to the write scope.
    Figure 2. OAuth 2.0 Consent Screen

  3. The resource owner selects the Allow button to grant consent for the write scope.

    The authorization server redirects the resource owner to the URL specified in the redirect_uri parameter.

  4. Inspect the URL in the browser.

    It contains a code parameter with the authorization code the authorization server has issued.

    For example:

    http://www.example.com/?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient

  5. The client performs the steps in Exchange an authorization code for an access token to exchange the authorization code for an access token.

Obtain an authorization code without using a browser

This procedure assumes the following configuration:

  • AM is configured as an OAuth 2.0 authorization server. Ensure that:

    • The code plugin is configured in the Response Type Plugins field.

    • The Authorization Code grant type is configured in the Grant Types field.

    For more information, see Authorization server configuration.

  • A confidential client called myClient is registered in AM with the following configuration:

    • Client secret: forgerock

    • Scopes: write

    • Response Types: code

    • Grant Types: Authorization Code

For more information, see Client registration.

Perform the steps in this procedure to obtain an authorization code without using a browser:

  1. The resource owner logs in to the authorization server, for example, using the credentials of the demo user.

    For example:

    $ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    "tokenId":"AQIC5wM…​TU3OQ*",
    "successUrl":"/openam/console",
    "realm":"/alpha"
}

  2. The client makes a POST call to the authorization server’s authorization endpoint, specifying the SSO token of the demo in a cookie and, at least, the following parameters:

    • client_id=your-client-id

    • response_type=code

    • redirect_uri=your-redirect-uri

    • decision=allow

    • csrf=demo-user-SSO-token

    For information about the parameters supported by the /oauth2/authorize endpoint, see /oauth2/authorize.

    If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /alpha realm, then use /oauth2/realms/root/realms/alpha/authorize.

    For example:

    $ curl --dump-header - \
--request POST \
--Cookie "iPlanetDirectoryPro=AQIC5wM…​TU3OQ*" \
--data "scope=write" \
--data "response_type=code" \
--data "client_id=myClient" \
--data "csrf=AQIC5wM…​TU3OQ*" \
--data "redirect_uri=https://www.example.com:443/callback" \
--data "state=abc123" \
--data "decision=allow" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/authorize"

    Note that the scope and the state parameters have been included. Scopes are not required, since they can be configured by default in the authorization server and the client, and have been added only as an example. The state parameter is added to protect against CSRF attacks.

    If the authorization server is able to authenticate the user and the client, it returns an HTTP 302 response with the authorization code appended to the redirection URL:

    HTTP/1.1 302 Found
Server: Apache-Coyote/1.1
X-Frame-Options: SAMEORIGIN
Pragma: no-cache
Cache-Control: no-store
Date: Mon, 30 Jul 2018 11:42:37 GMT
Accept-Ranges: bytes
Location: https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss=https%3A%2F%2Fopenam.example.com%3A8443%2Fopenam%2Foauth2&state=abc123&client_id=myClient
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Content-Length: 0

  3. Perform the steps in Exchange an authorization code for an access token to exchange the authorization code for an access token.

Exchange an authorization code for an access token

Perform the steps in the following procedure to exchange an authorization code for an access token:

  1. Ensure the client has obtained an authorization code by performing the steps in either Obtain an authorization code using a browser or Obtain an authorization code without using a browser.

  2. The client creates a POST request to the token endpoint in the authorization server specifying, at least, the following parameters:

    • grant_type=authorization_code

    • code=your-authorization-code

    • redirect_uri=your-redirect-uri

    For information about the parameters supported by the /oauth2/access_token endpoint, see /oauth2/access_token.

    Confidential clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

    • client_id=your-client-id

    • client_secret=your-client-secret

    For more information, see OAuth 2.0 client authentication.

    If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /alpha realm, then use /oauth2/realms/root/realms/alpha/access_token.

    For example:

    $ curl \
--request POST \
--data "grant_type=authorization_code" \
--data "code=g5B3qZ8rWzKIU2xodV_kkSIk0F4" \
--data "client_id=myClient" \
--data "client_secret=forgerock" \
--data "redirect_uri=https://www.example.com:443/callback" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"

    The client_id and the redirection_uri parameters specified in this call must match those used as part of the authorization code request, or the authorization server will not validate the code.

    The authorization server returns an access token in the access_token property. For example:

    {
  "access_token": "sbQZuveFumUDV5R1vVBl6QAGNB8",
  "scope": "write",
  "token_type": "Bearer",
  "expires_in": 3599
}

    The authorization server can also issue refresh tokens at the same time the access tokens are issued. For more information, see Refresh tokens.