Using the Authorization Code Flow with OpenID Connect

Use the Authorization Code flow when you have clients that can securely maintain a client secret between themselves and the Authorization Server. The Authorization Code flow returns an Authorization Code to the client, which can then exchange the code for an ID Token and an Access Token directly.

This provides you with the benefit of not exposing any tokens to the user agent (such as a web browser) and possibly other malicious applications with access to the user agent. The Authorization Server can also authenticate the client before exchanging the Authorization Code for an Access Token. The Authorization Code flow works with both Confidential Clients and Public Clients.

Confidential Clients

There are two steps in the Authorization Code flow:

1. Request the Authorization Code. In this request, the scope parameter value is openid. This is an OpenID Connect specification value.

   Request Example

   https://tenant-base-url/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=openid

   Response Example

   http://tenant-base-url/?code=AQIDBAXv9lZQ....F9NCA=

   • You can provide additional scope values in your requests, for example:

     https://tenant-base-url/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=phone+openid+offline_access+profile+address+email 

   • This request contains both the openid and an OAuth resource scope:

     https://tenant-base-url/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=http://tenant-base-url/api+openid

2. Request the Token. The client extracts the code parameter from the response and makes the token request. Also, the client provides its client id and secret as part of the Basic Authentication header.

   Request Example

   curl -i
   -H 'Authorization: Basic ZWE1OGIwNDA0N2ZkNGQ4MTgyYThiYWQ0ZTNkMGFmZjU6ZGMxNGE4MjMtZGU2OC00YWNhLTg1OWUtMWNhZTJmNjQ0NTBi' 
   -H 'Accept: */*'
   --request POST 'https://tenant-base-url/oauth2/v1/token' -d 'grant_type=authorization_code&code=AQIDBAXv9lZQ???.jF9NCA'

   Response Example

   The request contains both the Access Token and the ID Token.

   {
   "access_token":"eyJ4NXQjUzI1???.xhtnbw",
   "token_type":"Bearer",
   "expires_in":27261,
   "id_token":"eyJ4NXQjUzI1???.._XLqUw"
   }

Public Clients

Public clients don't have credentials, rather they have a client identifier. There are two steps in the Authorization Code flow. The requests involve a browser-based GET request, and then a back-channel POST request to get the Access Token.

1. Request the Authorization Code.

   Request Example

   GET https://tenant-base-url/oauth2/v1/authorize?client_id=<client-id>&response_type=code&redirect_uri=<client-redirect-uri>&scope=openid&nonce=<nonce-value>&state=1234

   Response Example

   Note:

   These request and response examples are similar to the Confidential Client request and responses discussed previously.

   http://tenant-base-url/?code=AQIDBAXv9lZQ....F9NCA=

2. Request the Token.

   Request Example

   Note:

   This request is different from the Confidential Client request where the client id and client secret are specified in the Basic Authentication header. In the public client flow, there is no Basic Authentication header. The client id is specified as part of the request payload.

   curl -i
   -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'
   --request POST https://tenant-base-url/oauth2/v1/token -d 'grant_type=authorization_code&code=<authz-code>&reidrect_uri=<client-redirect-uri>&client_id=<client-id>'

   Response Example

   {
   "access_token":"eyJ4NXQjUzI1???.xhtnbw",
   "token_type":"Bearer",
   "expires_in":27261,
   "id_token":"eyJ4NXQjUzI1???.._XLqUw"
   }