Hybrid flow

📘
Prerequisite

Setup the OpenID Connect custom application

When using the Hybrid Flow, some tokens are returned from the Authorization Endpoint, and others are returned from the Token Endpoint. The mechanisms for returning tokens in the Hybrid Flow are specified below:

"response_type" value	Flow	Tokens received at the "authorize" endpoint	Tokens received at the "token" endpoint
code token	Hybrid	Authorization code & ID token are returned	Both ID & access tokens are returned
code id_token	Hybrid	Authorization code & access token are returned	Both ID & access tokens are returned
code token id_token	Hybrid	Authorization code, access & ID token are returned	Both ID & access tokens are returned

How does it work?

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, ID token, and/or access token based on the response type.
The 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 hybrid code flow

The first endpoint to be invoked is the /oauth2/authorize/ endpoint. The response_type is set to code id_token (or) code token (or) code token id_token to indicate that it is an hybrid flow:

GET https://{tenant_url}/oauth2/authorize/{application_id}?scope={scope}&response_type=code id_token&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 and ID token or access token based on the response type 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%2C%20id_token&amp;code=Me-9AU-fP...&amp;id_token=eyJhbGciEM...&amp;scope=openid%20profile%20email">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}&assertion={id_token}

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

{
    "id_token": "eyJhbGci...",
    "refresh_token": "A2GUm...",
    "access_token": "eyJhbGc...",
    "token_type": "Bearer",
    "expires_in": 18000,
    "scope": <scopes>
}