Available OAuth 2.0 grant types with instructions

Requirements

• All traffic should be handled over a HTTPS connection
• A client that is configured for the grant type you wish to use with correct redirect uri(s)

Authorization Code

For apps running on a web server that is implemented using server-side frameworks such as Laravel, Drupal etc. we recommend Authorization Code grant with PKCE for browser-based and mobile native apps.

The client will redirect the user to the Identity Platform with the following parameters in the query string:

• response_type with the value code
• client_id with the client identifier
• redirect_uri with the client redirect URI. This parameter is optional, but if not send the user will be redirected to a pre-registered redirect URI.
• scope a space delimited list of scopes
• state with a CSRF token. This parameter is optional but highly recommended. You should store the value of the CSRF token in the user’s session to be validated when they return.

All of these parameters will be validated by the Identity Platform.

The user can be asked to login to the Identity Platform and approve the client, but by default everyone that integrates with us is a first-party client so this step will always be skipped for the user for convenience.

If the user approves the client they will be redirected from the Identity Platform to the client’s redirect URI with the following parameters in the query string:

• code with the authorization code
• state with the state parameter sent in the original request. You should compare this value with the value stored in the user’s session to ensure the authorization code obtained is in response to requests made by this client rather than another client application.

The client will now send a POST request to the Identity Platform with the following parameters:

• grant_type with the value of authorization_code
• client_id with the client identifier
• client_secret with the client secret
• redirect_uri with the same redirect URI the user was redirect back to
• code with the authorization code from the query string

Note that you need to decode the code query string first. For PHP you can do that with urldecode on the code itself.

The Identity Platform will respond with a JSON object containing the following properties:

• token_type with the value Bearer
• expires_in with an integer representing the TTL of the access token
• access_token a JWT signed with the Identity Platform private key
• refresh_token an encrypted payload that can be used to refresh the access token when it expires.

Client credentials 

For application access without a user present. This grant is suitable for machine-to-machine authentication, for example for use in a cron job which is performing maintenance tasks over an API. Another example would be a client making requests to an API that don’t require user’s permission.

The client sends a POST request with following body parameters to the Identity Platform:

• grant_type with the value client_credentials
• client_id with the client’s ID
• client_secret with the client’s secret
• scope with a space-delimited list of requested scope permissions.

The Identity Platform will respond with a JSON object containing the following properties:

• token_type with the value Bearer
• expires_in with an integer representing the TTL of the access token
• access_token a JWT signed with the Identity Platform’s private key

Authorization Code grant with PKCE

Recommended for clients without a secret, for example our Unify Top Layer is using it. Think of native mobile apps and web based apps to use this grant.

Before your application can issue tokens via the authorization code grant with PKCE, you will need to create a PKCE-enabled client.

Code verifier and code challenge

As this authorization grant does not provide a client secret, developers will need to generate a combination of a code verifier and a code challenge in order to request a token.

The code verifier should be a random string of between 43 and 128 characters containing letters, numbers, and "-", ".", "_", "~" characters, as defined in the RFC 7636 specification.

The code challenge should be a Base64 encoded string with URL and filename-safe characters. The trailing '=' characters should be removed and no line breaks, whitespace, or other additional characters should be present.

Redirecting for authorization

Once a client has been created, you may use the client ID and the generated code verifier and code challenge to request an authorization code and access token from your application. First, the consuming application should make a redirect request to the Unify Identity Platform "authorize" route.

Converting authorization codes with access tokens

If the user approves the authorization request, they will be redirected back to the consuming application. The consumer should verify the state parameter against the value that was stored prior to the redirect, as in the standard Authorization Code Grant.

If the state parameter matches, the consumer should issue a POST request to your application to request an access token. The request should include the authorization code that was issued by your application along with the originally generated code verifier. If the client is not first party, the user will first need to authorise the request, by default all clients are first party for the Identity Platform.

Refresh

Access tokens eventually expire; however some grants respond with a refresh token which enables the client to refresh the access token.

The client sends a POST request with following body parameters to the Identity Platform:

• grant_type with the value refresh_token
• refresh_token with the refresh token
• client_id with the the client’s ID
• client_secret with the client’s secret
• scope with a space-delimited list of requested scope permissions. This is optional; if not sent the original scopes will be used, otherwise you can request a reduced set of scopes.

The Identity Platform will respond with a JSON object containing the following properties:

• token_type with the value Bearer
• expires_in with an integer representing the TTL of the access token
• access_token a new JWT signed with the Identity Platform private key
• refresh_token an encrypted payload that can be used to refresh the access token when it expires