How To: Perform an OpenID Connect 1.0 Authorization Code Grant

The OpenID Connect 1.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). OpenID Connect 1.0 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

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 <Base64UrlEncodedHeader>.<Base64UrlEndcodedPayload>.<Base64UrlEncodedSignature> 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"
}

Related sections

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