Rate this page

Authorization Code Grant Type

The authorization code grant type is intended to be used by user-facing web applications with a server-side component. When the user grants authorization, the Ping Identity Data Governance Broker’s authorization endpoint provides the client with a short-lived authorization code, which it may then exchange for an access token using a back channel request that is inaccessible to the end user or the web browser. This limits the exposure of the access token. Of the supported OAuth 2 grant types, the authorization code grant type offers the best combination of security and features.

Authorization request

This is a two-step flow. The first request is a GET to the authorization endpoint (/oauth/authorize) performed by a web browser. If the request contains the openid scope, then it is also considered an authentication (OpenID Connect) request, and an ID token will be issued. If the request contains the offline_access scope and prompt=consent, then a refresh token will be issued.

GET /oauth/authorize

Parameter Required? Description
response_type yes Value must be code.
client_id yes The client ID.
redirect_uri no A redirect URI registered to the client. The authorization response will redirect to this URI.
scope no A space-delimited set of scope names. If omitted, the client’s default scopes are used. If an ID token is desired, then the openid scope should be provided. If a refresh token is desired, then the offline_access scope must be provided.
state no A value that the client may use to maintain state between the request and the redirect response. This can be used to mitigate the possibility of CSRF attacks.
nonce no A value that the client may use to associate a client-specific session with the end user’s authentication state at the server. This will be passed through as-is to the ID token.
prompt no Used by the client to direct the server’s behavior when logging in or prompting the end user for consent. Value may be none, login, consent, or login consent. If a refresh token is desired, then the value must include consent.
max_age no A value that the client may use to specify the maximum elapsed time in seconds since the user was last authenticated. This allows the client to force re-authentication after the given interval.
acr_values no A space-delimited set of authentication context class reference values. This allows the client to dictate the security level of an authentication request; the server may require second factor authentication based on this parameter.

Scopes requested using this grant type must be of type Generic or Authenticated Identity.

Example authorization request:

https://example.com/oauth/authorize?response_type=code
&client_id=<clientId>
&redirect_uri=https://example.com/callback/
&scope=openid+email+offline_access
&prompt=consent
&state=c291cyBsZXMgcGF2w6lzLCBsYSBwbGFnZQ==

The Data Governance Broker will respond with a redirect to the client’s redirect URI, appending the following query parameters:

Authorization response

Parameter Provided? Description
code always A short-lived authorization code.
state The same state value provided in the authorization request.

Example authorization redirect response:

https://example.com/callback/?code=AXxINZiqwlLFWkS0_kG78XJRoTxyAAAAAAAAAABEVRa49G-P0e1hqiufRQxzRLxGhKQfGlsfvB0tKZrhELGdnck_3j1JnI5Ivkx6Nq2DOfVM9RjCyesP6VsrHsvB6rPXECRH2FKHTlO9T8D15A&state=c291cyBsZXMgcGF2w6lzLCBsYSBwbGFnZQ==

At this point, the client should read the code and state query parameters, confirming that the state value is as expected.

Token request

After an authorization code has been received, the client then sends a POST request to the token endpoint (/oauth/token) with the authorization code. This is a server-to-server request and must not be performed through a web browser.

POST /oauth/token

The client uses HTTP basic authentication with its client ID and client secret to authenticate itself to the token endpoint and must specify a Content-Type of application/x-www-form-urlencoded. The following parameters are provided in the body of the request using form-urlencoding.

Parameter Required? Description
grant_type yes Value must be authorization_code.
code yes The authorization code appended to the redirect URI in the previous redirect response.
redirect_uri yes The previously used redirect_uri value.

Example token request:

POST /oauth/token HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic dGVzdDE6cGFzc3dvcmRwYXNzd29yZHBhc3N3b3JkcGFzc3dvcmQ=
Connection: keep-alive
Content-Length: 239
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com:443

grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback%2F&code=AXxINZiqwlLFWkS0_kG78XJRoTxyAAAAAAAAAADiQ8A5ZaEhAODxditL8vQr6TUl3PkR-SKRFiLcF-fesEZLnBmArwT-V9BE7HqqLIp9goZPGrgOUPSzJOwynOPmZAV8lAKjcpCiwkGsn-EAYQ

Token response

If the token request succeeds, the server will respond with a 200 response code.

Field Type Provided? Description
access_token string always The access token.
token_type string always The access token type. The value is always Bearer.
id_token string The ID token, if one was requested.
refresh_token string The refresh token, if one was requested.
expires_in number always A value in seconds indicating the lifetime of the access token.
scope string always A space-delimited set of the scopes actually granted. This may be a subset of the requested scopes.

Example token response:

HTTP/1.1 200 OK
Content-Length: 579
Content-Type: application/json
Date: Mon, 18 Apr 2016 23:21:10 GMT
Pragma: no-cache
Cache-Control: no-store

{
    "access_token": "eyJraWQiOiJBY2Nlc3MgVG9rZW4gU2lnbmluZyBLZXkgUGFpciIsImFsZyI6IlJTNTEyIn0.eyJzdWIiOiJVc2Vyc1wvOTkyM2RiYjgtZTdjNi00NjlmLWI3ZGItYWY3OTMxNzc0MDQ0Iiwic2NvcGUiOiJvcGVuaWQgb2ZmbGluZV9hY2Nlc3MgZW1haWwiLCJleHAiOjE0NzUzMzcyNDAsImlhdCI6MTQ3NDkwNTI0MCwiY2xpZW50X2lkIjoidGVzdDEiLCJqdGkiOiJhLjBKZ1hQdyJ9.LmxA4qnkghcrWVt_OjcWRa0lHQIxpAhJVamRHSuj4hJ38AG0CM-9BMS8JLu3L8iyQ_cAsh_g9zR_cVbJT-977DfaStI7UJlv0al4qTlilaqd7VD2lYHMP_r5h43yJ3B7oc3yv0488hBnKWilm0I060rLzVa7Nw0_sAOFrVWmbFm3QKCPCOmbDaWuOeYmMLz813kzpcmNBLX0TQuMgDhS89bfyOKQ-_uWdEpI-_y6_JfYdER2cB0WCRt54VBhYTehSJxGC31DGyFnjvPDqFQQ9V8iGty5MMyarfO2qazco5tr-Wp6lD4X2yLad3qQ62wcn5tDrw_n7qajIOQMFi-c8w",
    "refresh_token": "AXpKY5sxMMSdJ6BsSLk7k909SvyUAAAAAAAAAAArP5-fT6w5dnEdReZpfrpSZ-hFAvrw75sAMdoyF_KSijRgQs1JS-iO2dZln_FGap3qc_Hv3uAeqccbINh4pXOhu1uoWAHNoxOsOMYPl-C6Dw",
    "expires_in": 43200,
    "id_token": "eyJraWQiOiJyc2EtaWR0b2tlbiIsImFsZyI6IlJTMjU2In0.eyJhdF9oYXNoIjoiMk5hbWZVdW45aTBkR2pFMWh3Q2lZUSIsImFjciI6IkRlZmF1bHQiLCJzdWIiOiJVc2Vyc1wvOTkyM2RiYjgtZTdjNi00NjlmLWI3ZGItYWY3OTMxNzc0MDQ0IiwiYXVkIjoidGVzdDEiLCJhbXIiOlsicHdkIl0sImF1dGhfdGltZSI6MTQ3NDg5ODE4NCwiaXNzIjoiaHR0cHM6XC9cL2V4YW1wbGUuY29tIiwiZXhwIjoxNDc0OTA2MTQxLCJpYXQiOjE0NzQ5MDUyNDF9.MbViGXd04lJ0JhlsDIPr83dGS0zPrNw2M7PchBj7sA0AN6ifhEEG5qGwyr-QtkZynBbpt3i1sycBiIHhNZ48HUWOAV-iE5ntQ-HG9OqoFrc0xu-EXRG42EhvCvGZItRuDRkpIpNrfrHNQJJCLA8EQxP2HLiA-Xj9S0sR-ggz0Eo2jRoWb-dmg7re6RY345DlCrQBWytZCFBDujqrBacEJNQbtaBCTQl0aJPywOuU7Mm-_7-dm8u8kC8CEh2q3RF7Zrhn76y_EqKqHQTfGbSINok4kMw7cIazvIIrq4eVMCk7vAP7kfgMU824dCePlUXkNwiRALKUV6quCC3dQ4wXrA",
    "scope": "email openid offline_access",
    "token_type": "Bearer"
}