Integrate the authorization code flow

This topic explains how to use an authorization code flow with CyberArk Identity.

The authorization code flow is used to obtain access, ID, and refresh tokens and is mainly designed for confidential clients. This redirection-based flow requires the user's authentication with the IdP.

Before you begin

Set up the OpenID Connect custom application.

How it works

In this flow:

  1. The client application (or relying party), in this case, the bank, sends an authorization request with the client ID and client secret toCyberArk Identity, which acts as the authorization server.

  2. CyberArk Identity authenticates the user and redirects the user with an authorization code.

  3. The bank sends a token request by passing the authorization code and client secret.

  4. CyberArk Identity validates the token request and returns the access and ID tokens. Optionally, refresh tokens are also returned.

  5. The bank uses the ID and access token to make further calls to the resource server and to validate the user.

Integrate the CyberArk Identity authorization code flow

The first endpoint to be invoked is the /oauth2/authorize/ endpoint. The response_type is set to code to indicate that it is an authorization code flow:

GET https://{tenant_url}/oauth2/authorize/{application_id}?scope={scope}&response_type=code&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}

If the user is not authenticated to CyberArk Identity, the response contains HTML with a redirect URI to a login page:

<html><head><title>Object moved</title></head>


<h2>Object moved to <a href="/login?cloudRedirect=Oauth2%2FAuthorize%2Ftest%3Fbounce%3DKZhmpLy...">here</a>.</h2>



The client invokes the cloud redirect URI mentioned above by appending the tenant URL:

GET {tenant_url}/login?cloudRedirect=Oauth2%2FAuthorize%2Ftest%3Fbounce%3DKZhmpLy...

As the user authenticates through the login page, the Start Authentication and Advance Authentication endpoints are invoked.

When the user successfully fulfills the security challenge(s), the /oauth2/authorize/{app ID} endpoint is invoked internally. This time, the response contains an authorization code in the code query parameter of the redirect URI returned:

<html><head><title>Object moved</title></head>


<h2>Object moved to <a href="{redirect_uri}?responseType=code&amp;code=WXlxkM9dSk...">here</a>.</h2>



The client invokes the /token/ endpoint to exchange the authorization code for an access token and ID token by passing the full redirect URI in the redirect_uri parameter using form serialization. The authorization code is specified in the URI's code query parameter, and grant_type is set to authorization_code:

POST {tenant_url}/oauth2/token/{application_id} HTTP/1.1

Content-Type: application/x-www-form-urlencoded

Body parameters should be sent as form urlencoded


The response contains the access, ID, and refresh token:


"id_token": "eyJhbGci...",

"refresh_token": "A2GUm...",

"access_token": "eyJhbGc...",

"token_type": "Bearer",

"expires_in": 18000,

"scope": <scopes>


The access token can then be used in subsequent API calls by including it in the Authorization header and the token type. For example:

ExamplePOST {tenant_url}/security/whoami HTTP/1.1

Authorization: Bearer eyJhbGciOi...