Integrate authentication using OIDC Authorization Code flow

📘
Prerequisite

Setup OpenID Connect (OIDC) custom application in CyberArk Identity tenant

Install the CyberArk Identity Java SDK

The CyberArk Identity OpenID Connect (OIDC) custom application template supports the Authorization Code Flow with Proof Key for Code Exchange (PKCE)..

This guide describes how authorization code with PKCE can be integrated with CyberArk Identity using the CyberArk Identity Java SDK.

Create a Code Verifier and Code Challenge

For authorization code with PKCE flow, code verifier and code challenge should be generated and passed to the authorization and token requests. The Java SDK provides the below methods to create a code verifier and code challenge.

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

The code verifier is a cryptographically random string that uses the characters A-Z, a-z, 0-9, and the 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.

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

Configure an OIDC Client instance

Configure the OIDC client instance as below:

import com.cyberark.client.OIDCClient; 

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

Build an authorize URL

The client application should send an authorization request using AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider as shown below:

AuthorizeUrlBuilder authorizeUrlBuilder = oidcClient.authorizeUrl(YOUR_REDIRECT_URL)
    .setResponseType("code")
    .setScope("openid email profile")
    .setCodeChallenge(codeChallenge)
    .setCodeChallengeMethod("S256");

// to get authorize URL
String authURL = authorizeUrlBuilder.build();

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

Note: The redirectUri must be white-listed in the Authorized Redirect URIs section under the Trust section of the OpenID Connect web application.

The user will be redirected to the redirect URI and the authorization code is sent as part of the redirect URI.

https://YOUR_REDIRECT_URI?responseType=code&code=YOUR_CODE

Exchange code for tokens

The authorization code received in the above step should be exchanged for access, ID, and optionally refresh tokens as shown below:

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

TokenHolder tokenHolder = tokenRequest.execute();