How To: Perform an OAuth Authorization Code Grant

The OAuth 2.0 Authorization Code Grant is typically used in situations where an App uses it's own backend server, and this server needs an access token to call the API's from The Identity Hub. As the server cannot interact with the user, this is left up to the client App running on the user agent (mostly a browser).

The flow is as follows

Step 1: Initiating the flow

Sending the request

To signin and obtain an access token for the user, you initiate this flow by redirecting the user to the following url:

Example request

GET /{tenant}/oauth2/v1/auth/?response_type=code&client_id=[YOUR_CLIENT_ID]&redirect_uri=https://[YOUR_APP_REDIRECT_URI]/&scope=[SCOPES]&state=[STATE] HTTP/1.1

The Identity Hub also supports the use of Proof Key for Code Exchange (PKCE), please refer to GET {tenant}/oauth2/v1/auth documentation for more details.

Handling the response

After the user authenticates, we will redirect the authorization code to https://[YOUR_APP_REDIRECT_URI]/

The authorization code will be sent to the server via the query parameters in the url.

Example response

https://[YOUR_APP_REDIRECT_URI]/?code=X5678IYHI690UJJJ000&state=[STATE]

Step 2. Exchanging the authorization code for an access token

Once the web server receives the authorization code, it can exchange this code for an access token.

Sending the request

To exchange the authorization code the server uses a http post and sends the authorization code in the body, together with the App's credentials. The redirect uri used in the request for the authorization code must also be present.

Example request

POST /{tenant}/oauth2/v1/token/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=X5678IYHI690UJJJ000
&client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]
&redirect_uri=[YOUR_APP_REDIRECT_URI]

If the authorization code was requested in Step 1. using Proof Key for Code Exchange (PKCE) technique, please refer to POST {tenant}/oauth2/v1/token documentation for more details.

Handling the response

Upon receiving the request to exchange the authorization code, The Identity Hub will verify the App's credentials and issue an access token if the authorization code is valid and the redirect uri matches the redirect uri from the previous request for an auhorization code.

The body of the response will contain a json result, including the access token, validity of the token and a refresh token.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"7779HHKHKHKK6683TY3",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"703JH3YU89YH389T3878T38"
}

Step 3: Exchanging a refresh token for an access token.

The refresh token can be used to ask for a new access token.

Sending the request

The server must post the refresh token and provide the App's credentials to authenticate itself.

Example request

POST /{tenant}/oauth2/v1/token/ HTTP/1.1
Host: theidentityhub.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=703JH3YU89YH389T3878T38
&client_id=[YOUR_CLIENT_ID]
&client_secret=[YOUR_CLIENT_SECRET]
    

Handling the response

A new access token and refresh token will be returned as a json result, if the credentials and refresh token are still valid.

The body of the response will contain a json result, including the access token, validity of the token and a refresh token.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"357G9729HSFYZEJHZH",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"923720HDUZDZGDKJQKJ9873"
}

Related sections

GET {tenant}/oauth2/v1/auth
POST {tenant}/oauth2/v1/token
GET {tenant}/oauth2/v1/verify