Authorization Code Grant with PKCE

The relying party (the client) must be able to generate a code verifier and a code challenge. For details, see the PKCE standard (RFC 7636). The information contained in this procedure is for example purposes only:

1. The client generates the code challenge and the code verifier. Creating the challenge using a SHA-256 algorithm is mandatory if the client supports it, as per the RFC 7636 standard.

   The following is an example of a code verifier and code challenge written in JavaScript:

   function base64URLEncode(words) {
      return CryptoJS.enc.Base64.stringify(words)
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '');
   }
   var verifier = base64URLEncode(CryptoJS.lib.WordArray.random(50));
   var challenge = base64URLEncode(CryptoJS.SHA256(verifier));

   This example generates values such as ZpJiIM_G0SE9WlxzS69Cq0mQh8uyFaeEbILlW8tHs62SmEE6n7Nke0XJGx_F4OduTI4 for the code verifier and j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y for the code challenge. These values will be used in subsequent procedures.

   The relying party is now ready to request an authorization code.

2. The relying party performs the steps in one of the following procedures to request an authorization code:

   • "To Obtain an Authorization Code Using a Browser in the Authorization Code Grant with PKCE Flow"

   • "To Obtain an Authorization Code Without Using a Browser in the Authorization Code Grant with PKCE Flow"

This procedure assumes the following configuration:

For more information, see Dynamic Client Registration.

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

1. The relying party redirects the end user's user-agent to the AM's authorization endpoint specifying, at least, the following query parameters:

   • client_id=your_client_id

   • response_type=code

   • redirect_uri=your_redirect_uri

   • code_challenge=your_code_challenge

   • code_challenge_method=S256

   • scope=openid profile

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

   If the OAuth 2.0/OpenID 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/OpenID provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   https://openam.example.com:8443/openam/oauth2/realms/root/authorize \
   ?client_id=myClient \
   &response_type=code \
   &scope=openid%20profile \
   &redirect_uri=https://www.example.com:443/callback \
   &code_challenge=j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y \
   &code_challenge_method=S256 \
   &nonce=123abc \
   &state=abc123

   Note that the URL is split and spaces have been added for readability purposes. The state and nonce parameters have been included to protect against CSRF and replay attacks.

2. The end user authenticates to AM, 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, AM presents its consent screen:

   OpenID Connect Consent Screen

   

   Note that requesting the profile scope translates into requesting access to several claims. For more information about the special profile scope, see Claims.

   
   

3. The end user selects the Allow button to grant consent for the profile scope.

   AM redirects the end user 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 AM has issued. For example:

   https://www.example.com:443/callback?code=g5B3qZ8rWzKIU2xodV_kkSIk0F4&iss=https://openam.example.com:8443/openam/oauth2&state=abc123&client_id=myClient

5. The client performs the steps in "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant with PKCE Flow" to exchange the authorization code for an ID/access token.

This procedure assumes the following configuration:

For more information, see Dynamic Client Registration.

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

1. The end user logs in to AM, 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/authenticate'
   {
       "tokenId":"AQIC5wM...TU3OQ*",
       "successUrl":"/openam/console",
       "realm":"/"
   }

2. The client makes an HTTP POST request to AM's authorization endpoint, specifying in a cookie the SSO token of the demo 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

   • code_challenge=your_code_challenge

   • code_challenge_method=S256

   • scope=openid profile

     You can configure the openid scope as a default scope in the client profile or the OAuth 2.0/OpenID provider to avoid including the scope parameter in your calls, if required.

     However, since the openid scope is required in OpenID Connect flows, the example specifies it.

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

   If the OAuth 2.0/OpenID 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/OpenID provider is configured for the /customers realm, then use /oauth2/realms/root/realms/customers/authorize.

   For example:

   $ curl --dump-header - \
   --request POST \
   --Cookie "iPlanetDirectoryPro=AQIC5wM...TU3OQ*" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "scope=openid profile" \
   --data "response_type=code" \
   --data "client_id=myClient" \
   --data "csrf=AQIC5wM...TU3OQ*" \
   --data "state=abc123" \
   --data "nonce=123abc" \
   --data "decision=allow" \
   --data "code_challenge=j3wKnK2Fa_mc2tgdqa6GtUfCYjdWSA5S23JKTTtPF8Y" \
   --data "code_challenge_method=S256" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/authorize"

   Note that the state and nonce parameters have been included to protect against CSRF and replay attacks.

   If AM 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&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 "To Exchange an Authorization Code for an ID/Access Token in the Authorization Code Grant with PKCE Flow" to exchange the authorization code for an ID/access token.

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

1. Ensure the client has obtained an authorization code by performing the steps in either "To Obtain an Authorization Code Using a Browser in the Authorization Code Grant with PKCE Flow" or "To Obtain an Authorization Code Without Using a Browser in the Authorization Code Grant with PKCE Flow".

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

   • client_id=your_client_id

   • redirect_uri=your_redirect_uri

   • code_verifier=your_code_verifier

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

   For example:

   $ curl --request POST \
   --data "grant_type=authorization_code" \
   --data "code=g5B3qZ8rWzKIU2xodV_kkSIk0F4" \
   --data "client_id=myClient" \
   --data "redirect_uri=https://www.example.com:443/callback" \
   --data "code_verifier=ZpJiIM_G0SE9WlxzS69Cq0mQh8uyFaeEbILlW8tHs62SmEE6n7Nke0XJGx_F4OduTI4" \
   "https://openam.example.com:8443/openam/oauth2/realms/root/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 AM will not validate the code.

   AM returns an ID and an access token. For example:

   {
      "access_token":"cnM3nSpF5ckCFZOaDem2vANUdqQ",
      "scope":"openid profile",
      "id_token":"eyJ0eXAiOiJKV1QiLCJra...7r8soMCk8A7QdQpg",
      "token_type":"Bearer",
      "expires_in":3599
   }

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

   Tip

   AM can also issue refresh tokens at the same time the access tokens are issued. For more information, see Refresh Tokens.

3. (Optional) The relying party can request additional claims about the end user from AM.

   For more information, see "/oauth2/userinfo".