Integrate the OIDC Authorization Code

Overview

The CyberArk Identity OpenID Connect (OIDC) custom application template supports the Authorization Code Flow with Proof Key for Code Exchange (PKCE). The flow is preferable when configuring public applications, such as mobile apps or single-page apps, where storing the client secrets is not secure. The OIDC Authorization Code flow for public applications requires that you do not use a client secret when configuring the application template.

Before you begin

• Set up the OpenID Connect (OIDC) custom web application in your tenant using the steps below.

  Refer to Configuring the custom OpenID Connect application

• Refer to CyberArk Identity Java SDK reference for more information on the Java SDK.

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 Code Challenge

Before redirecting the user to the authorization server, the client must first generate a secret code verifier and 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 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 an OIDCClient instance.

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);

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 the OpenID Connect web application.

The CyberArk Identity provider supports SHA256 hash as a 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")
    .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&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

Exchanged the code received from the previous step to get the access_token and id_token using the oidcClient instance.

The Refresh Token is available only when the authorization code is exchange 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

Use the access_token to get User Info.

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.