Integrate the OAuth Authorization Code with PKCE

This topic describes the Java SDK OAuth Authorization Code flow with Proof Key for Code Exchange (PKCE) integration.

Overview

The CyberArk Identity OAuth2 custom application template supports the Proof Key for Code Exchange (PKCE) when configuring public applications, such as mobile apps or single-page apps, where the client secret is not secure. The PKCE OAuth2 flow for public applications requires that you do not use a client secret when configuring the application template. Refer to Authorization (Auth) Code Flow with PKCE for more information.

Before you begin

Integrate the SDK

Follow the steps below to use this SDK to get the access_token.

Step 1: Create a Code Verifier and Code Challenge

Before redirecting a 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 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 generates 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 OAuthClient instance using the Java SDK

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

// client secret parameter is not required for PKCE Flow
OAuthClient oauthClient = new OAuthClient(YOUR_TENANT_URL, YOUR_OAUTH_APPLICATION_ID, YOUR_USER_ID);

Step 3: Build the authorize URL

Create an AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider. The redirectUri must be added to allowed list in the Redirect destinations section, under the General Usage section of the OAuth client application.

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

Now the client can include the codeChallenge parameter in the request, which the authorization server stores and compare during the code exchange step.

Call the following builder methods using the oauthClient instance.

AuthorizeUrlBuilder authorizeUrlBuilder = oauthClient.authorizeUrl(YOUR_REDIRECT_URL)
    .setResponseType("code")
    .setScope(YOUR_SCOPE)
    .setCodeChallenge(codeChallenge)
    .setCodeChallengeMethod("S256");

// to get authorize URL
String authURL = authorizeUrlBuilder.build();
https://YOUR_TENANT_URL/OAuth2/Authorize/YOUR_OAUTH_APPLICATION_ID?redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_USER_ID&scope=YOUR_SCOPE&response_type=code&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&code=YOUR_CODE

Step 4: Exchange the code with the token

Exchange the code received in the previous step to get the access_token using the oauthClient instance.

// codeVerifier stored in the previous step

TokenRequest tokenRequest = oauthClient.requestToken(YOUR_CODE, YOUR_REDIRECT_URL)
    .setGrantType("authorization_code")
    .setCodeVerifier(codeVerifier);

TokenHolder tokenHolder = tokenRequest.execute();
{
  access_token: "YOUR_ACCESS_TOKEN",
  expires_in: 18000,
  refresh_token: "YOUR_REFRESH_TOKEN",
  scope: "all",
  token_type: "Bearer"
}

Common Methods

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