Integrate OIDC Hybrid Flow

This topic describes the Java SDK OIDC Hybrid flow integration.

Overview

The OIDC Hybrid flow is the combination of both Authorization and Implicit flows. The hybrid flow is suggested when applications are able to securely store the client secrets as it allows immediate access to an ID (Short lived) token with safe and secure retrieval of access and refresh tokens in the next function.

Before you begin

Integrate the SDK

Follow the steps below to use this SDK to get the access_token, id_token, and User Info.

Step 1: Create a Code Verifier and a Code Challenge

Before redirecting the user to the authorization server, the client must first generate a secret code verifier and a code challenge.

The code verifier is a cryptographically random string using the characters A-Z, a-z, 0-9, and special characters -._~ (hyphen, period, underscore, and tilde), and is between 43 and 128 characters long.

Once the client has generated the code verifier, it uses that to create the code challenge. For devices that can perform a SHA256 hash, the code challenge is a BASE64-URL-encoded string of the SHA256 hash of the code verifier. Otherwise, the same verifier string is used as the code challenge.

Example:
The client needs to store the codeVerifier for later use.

String codeVerifier = PKCEUtil.generateCodeVerifier();
String codeChallenge = PKCEUtil.generateCodeChallenge(codeVerifier);

Step 2: Configure an OIDC Client instance

  • Import the SDK as specified in the Before you get started section.
  • Pass the required parameters to create OIDCClient instance.
import com.cyberark.client.OIDCClient; 

// client secret parameter is not necessary for Hybrid flow with PKCE.
OIDCClient oidcClient = new OIDCClient(YOUR_TENANT_URL, YOUR_OIDC_APPLICATION_ID, YOUR_CLIENT_ID);

Step 3: Build an authorize URL

Create an AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider. The redirectUri must be white-listed in the Authorized Redirect URIs section under the Trust section of theOpenID Connect web application.

The CyberArk Identity provider supports SHA256 hash as the signing algorithm.

The client includes the codeChallenge parameter in this request, which the authorization server stores and compares later during the code exchange step.

Call the following builder methods, using the oidcClient instance.

AuthorizeUrlBuilder authorizeUrlBuilder = oidcClient.authorizeUrl(YOUR_REDIRECT_URL)
    .setResponseType("code id_token token") //Ex: code is mandatory for hybrid flow
    .setScope("openid email profile")
    .setCodeChallenge(codeChallenge)
    .setCodeChallengeMethod("S256");

// to get authorize URL
String authURL = authorizeUrlBuilder.build();
https://YOUR_TENANT_URL/OAuth2/Authorize/YOUR_OIDC_APPLICATION_ID?redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_OIDC_CLIENT_ID&scope=openid email profile&response_type=code,id_token,token&code_challenge_method=S256&code_challenge=YOUR_CODE_CHALLENGE

Redirect to the authorize URL obtained above and post authentication with CyberArk Identity. In case of unauthentication, receive the code as part of the redirected URL mentioned above.

https://YOUR_REDIRECT_URI#responseType=code,%20token,%20id_token&code=YOUR_CODE&access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=18000&id_token=YOUR_ID_TOKEN&scope=openid%20email%20profile

Based on the requested response_type, code, id_token or access_token is received in the redirect resource itself.

📘

Supported Response types for Hybrid Flow

  • code token
  • code id_token
  • code id_token token

The short lived tokens are useful in accessing the resources by your front end applications to get immediate user identity.

The long lived tokens are used by backend applications along with refresh tokens to access the resources for a longer duration.

If we pass just code in setResponseType method, it is the Integrate OIDC Authorization Code flow.

Step 4: Exchange the code with the token

Using the OIDCClient instance, the code received from the previous step is exchanged to get the access_token and id_token.

The Refresh Token is available only when the authorization code is exchanged for the token.

TokenRequest tokenRequest = oidcClient.requestToken(YOUR_CODE, YOUR_REDIRECT_URL) 
  .setGrantType("authorization_code") 
  .setCodeVerifier(codeVerifier); // codeVerifier stored in the previous step.

TokenHolder tokenHolder = tokenRequest.execute();
{
  access_token: "YOUR_ACCESS_TOKEN",
  id_token: "YOUR_ID_TOKEN",
  expires_in: 18000,
  refresh_token: "YOUR_REFRESH_TOKEN",
  scope: "openid email profile",
  token_type: "Bearer"
}

Step 5: Get User Info

Using User Info method, use the access_token to get the user information.

UserInfo userInfo = oidcClient.userInfo(YOUR_ACCESS_TOKEN)
    .execute();
{
  aud: "518b31c8-225e-47c0-b489-2f091157eb5c",
  auth_time: 1636107642,
  email: "YOUR_USER_EMAIL",
  email_verified: true,
  family_name: "YOUR_USER_NAME",
  given_name: "YOUR_USER_NAME",
  name: "YOUR_USER_NAME",
  preferred_username: "YOUR_COMPLETE_USER_NAME",
  sub: "bcce5189-93a0-4bd4-91a9-d5f6ee0fa6e4",
  unique_name: "YOUR_COMPLETE_USER_NAME"
}

Common Methods

For common methods, such as refreshToken, revokeToken and claims, refer to CyberArk Identity Java SDK reference.

To ensure security best practices, CyberArk Identity recommends that you use the Authorization Code with PKCE flow.