Authorization code grant

Endpoints

/oauth2/authorize
/oauth2/access_token
/oauth2/userinfo (OpenID Connect [OIDC])

The authorization code grant flow for OAuth 2.0 and OIDC lets a confidential client, such as a web application running on a server, exchange an authorization code for an access token to get authorized access to protected resources.

The authorization code grant is secure because:

It is a two-step process:
1. The resource owner authenticates to the authorization server and authorizes the client to access the protected resource. The client receives a temporary authorization code from the server as confirmation.
2. The authorization server validates the authorization code and exchanges it for an access token.
The authorization server delivers the access token directly to the client, usually over HTTPS. Neither the access token nor the client secret is exposed publicly, which protects confidential clients.

The authorization code grant flow

OAuth 2.0

The client, usually a web-based service, receives a request to access a protected resource. To access the resource, the client requires authorization from the resource owner.
The client redirects the resource owner’s user-agent to the authorization server.
The authorization server authenticates the resource owner, confirms resource access, and gathers consent if not previously saved.
The authorization server redirects the resource owner’s user agent to the client.
During the redirection process, the authorization server appends an authorization code.
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.
If the authorization code is valid, the authorization server returns an access token (and a refresh token, if configured) to the client.
The client requests access to the protected resource from the resource server.
The resource server contacts the authorization server to validate the access token.
The authorization server validates the token and responds to the resource server.
If the token is valid, the resource server allows the client to access the protected resource.

OIDC

The end user wants to use the services provided by the relying party (RP). The RP, usually a web-based service, requires an account to provide those services.

The end user issues a request to share their information with the RP.
To access the end user’s information in the OpenID provider (OP), the RP requires end user consent.

The RP redirects the end user’s user-agent…
…to the OP.
The OP authenticates the end user, confirms resource access, and gathers consent if necessary.
The OP redirects the end user’s user-agent to the RP.
During the redirection process, the OP appends an authorization code.
The RP authenticates to the OP and exchanges the authorization code for an access token and an ID token.

Note that this example assumes a confidential client. Public clients are not required to authenticate.
If the authorization code is valid, the OP returns an access token and an ID token to the RP.
The RP validates the ID token and its claims.

The RP can use the ID token subject ID claim as the end user’s identity.
If the RP requires additional claims, it sends a request to the /oauth2/userinfo endpoint with the access token for authorization.
If the access token is valid, the /oauth2/userinfo endpoint returns any additional claims.

The RP can use the subject ID and the additional claims to identify the end user.

Demonstrate the authorization code grant flow

Follow these steps to get an authorization code and exchange it for an access token:

Prepare the demonstration
Get an authorization code using a browser or Get an authorization code using REST
Exchange an authorization code for an access token

Prepare the demonstration

This demonstration 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, refer to Authorization server configuration.
A confidential client called myClient is registered in AM with the following configuration:
- Client secret: forgerock
- Scopes: write (for OAuth 2.0)
  openid and profile (for OIDC)
- Response Types: code
- Grant Types: Authorization Code
For more information, refer to Client application registration.

Get an authorization code using a browser

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

client_id=your-client-id
response_type=code
redirect_uri=your-redirect-id

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

For OIDC, set scope=openid profile instead.

The URL is split and spaces added for readability purposes.

The scope parameter is optional if default values are configured in the authorization server or the client.

The state parameter is included to protect against CSRF attacks but is also optional.

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.
On a successful login, the authorization server presents the AM consent screen unless AM is configured to use implied consent.

Figure 1. OAuth 2.0 consent screen
Click Allow to consent.

The authorization server redirects the resource owner to the URL specified in the redirect_uri parameter.
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/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&scope=write&iss…
The client performs the steps in Exchange an authorization code for an access token to exchange the authorization code for an access token.

Get an authorization code using REST

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"
}

The client makes a POST call to the authorization server’s /oauth2/authorize endpoint, specifying the resource owner’s SSO token in a cookie, and the following parameters:

client_id=your-client-id
response_type=code
redirect_uri=your-redirect-uri
decision=allow
csrf=demo-user-SSO-token

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"

For OIDC, set scope=openid profile instead.

The scope parameter is optional if default values are configured in the authorization server or the client.

The state parameter is included to protect against CSRF attacks but is also optional.

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/2 302
…
location: https://www.example.com:443/callback?code=<authorization-code>&iss…
…

Follow the steps in Exchange an authorization code for an access token.

Exchange an authorization code for an access token

As the client, call the /oauth2/access_token endpoint to exchange the authorization code for an access token. Provide the following parameters:

grant_type=authorization_code
code=your-authorization-code
redirect_uri=your-redirect-uri

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, refer to OAuth 2.0 client authentication.

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 redirect_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.

For OAuth 2.0, the authorization server returns an access token; for example:

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

For OIDC, the OP returns an access token and an ID token; for example:

{
  "access_token": "<access-token>",
  "scope": "openid profile",
  "id_token": "<id-token>",
  "token_type": "Bearer",
  "expires_in": 3599
}

If the RP does not require the access token, revoke it.

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

Additional OIDC claims

An RP can request additional claims about the end user with the access token at the /oauth2/userinfo endpoint:

$ curl \
--request GET \
--header "Authorization Bearer <access-token>" \
"https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/userinfo"
{
  "name": "<resource-owner-display-name>",
  "family_name": "<resource-owner-family-name>",
  "given_name": "<resource-owner-given-name>",
  "sub": "<resource-owner-sub>",
  "subname": "<resource-owner-id>"
}

Access Management 7.3.1

Authorization code grant

The authorization code grant flow

OAuth 2.0

OIDC

Demonstrate the authorization code grant flow

Prepare the demonstration

Get an authorization code using a browser

Get an authorization code using REST

Exchange an authorization code for an access token

Additional OIDC claims