How To: Perform an OpenID Connect Authorization Code Grant

The OpenID Connect 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). OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

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 (for OpenID Connect, the openid scope is required) 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, refresh token and ID Token (JWT) 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:

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

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 response

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]

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 and the ID token, validity of the token and a refresh token. The ID token is in the format .. See http://openid.net/specs/openid-connect-core-1_0.html

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",
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
     yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
     NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
     fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
     AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
     Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
     NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
     QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
     K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
     XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

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