HomeProduct documentationGitHubCyberArk developer community

Authorization code flow

Suggest Edits

📘

Prerequisite

  1. Setup the OpenID Connect custom application

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.

How does it work?

1213

In this flow,

  • The client application (or relying party), The bank sends an authorization request with the client ID and client secret to CyberArk Identity, which acts as the authorization server.
  • CyberArk Identity authenticates the user and redirects the user with an authorization code.
  • Bank sends a token request by passing the authorization code and client secret.
  • CyberArk Identity validates the token request and returns the access and ID tokens. Optionally refresh tokens are also returned.
  • Bank uses the ID and access token to make further calls to the resource server and to validate the user.

Integrate CyberArk Identity's 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>
<body>
	<h2>Object moved to <a href="/login?cloudRedirect=Oauth2%2FAuthorize%2Ftest%3Fbounce%3DKZhmpLy...">here</a>.</h2>
</body>
</html>

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>
<body>
	<h2>Object moved to <a href="{redirect_uri}?responseType=code&amp;code=WXlxkM9dSk...">here</a>.</h2>
</body>

</html>

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 the 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

redirect_uri={redirect_uri}&code=HsOynOzaKL_yCo_-cJhh4xM...&grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&nonce=abc

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:

POST {tenant_url}/security/whoami HTTP/1.1

Authorization: Bearer eyJhbGciOi...

👍

Integrate authorization code flow using CyberArk Identity SDKs

CyberArk Identity provides SDKs to integrate authorization code flow into your applications.

Updated about 2 months ago