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

  • The app redirects the user to your authorization endpoint at /{tenant}/oauth2/v1/auth/, and provides some parameters to ask for an authorization code, including scopes and your redirection uri.
  • After the user authenticates and grants access if needed, The Identity Hub issues an Authorization Code, and redirects to your redirect uri together with this code in the query parameter.
  • Because the code was passed using a query parameter, your server can parse out the code and can post a request to your token endpoint (/{tenant}/oauth2/v1/token) at The Identity Hub, to exchange the authorization code for an access token.
  • Upon receipt of the authorization code, The Identity Hub will issue an access token and refresh token and return this as a json response to your server.
  • You can use the refresh token to exchange it for a new access token at the same token endpoint. As long as the refresh token is not expired and the user is not blocked or its rights were changed, you will receive another access token. As a result you server processes can access API's even if the user is offline.

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

Requesting an authorization code using the Authorization Code Grant