CyberArk Identity Java SDK OpenID Connect Quick Start Guide

Before you get started

Before you begin this guide, make sure you have the following:

  • CyberArk Identity Tenant
    • To start fresh, create your own CyberArk Free Trial account.
  • Setup OpenID Connect (OIDC) custom Application in your tenant with below steps

    Refer here for Configuring the custom OpenID Connect application

    • Make sure to provide the Application ID under the Settings section of the OIDC application.
    • On the Trust section of the OIDC application, configure Authorized Redirect URIs and Resource application URL in the CyberArk Identity Admin Portal . These are the endpoints of the host URL of the client application.
    • On the Permissions section of the OIDC application, add a role and provide run permission. This deploys the OIDC web application to the users mapped to the role.
  • CyberArk Identity Java SDK library can be obtained from the downloaded GitHub repository with the path ./spring-boot/libs/Authorization-1.0-SNAPSHOT.jar
    • Add the jar file dependency in your project pom.xml file.
<dependency>
            <groupId>com.cyberark.identity</groupId>
            <artifactId>OIDC</artifactId>
            <scope>system</scope>
            <version>1.0-SNAPSHOT</version>
            <systemPath>${project.basedir}/libs/Authorization-1.0-SNAPSHOT.jar</systemPath>
</dependency>

Introduction

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end user based on the authentication performed by an authorization server, as well as to obtain basic profile information about the end user.

Why this SDK?

This SDK provides an integration with CyberArk Identity OpenID Connect web app based on OAuth 2.0 standards in 10 minutes which brings the ease of managing users. At the end of this guide, your java server integrates with CyberArk Identity OpenID Connect web app for authentication.

Configure an OIDCClient instance using JAVA SDK

  • Import the SDK as specified in the Before you get started section
  • Create OIDCClient instance by passing the required parameters based on the flow you wish to use.

    Refer here for Configuring an OIDCClient instance.

  • After the OIDCClient instance is created, you can follow any one of these based on the application use case:
    • Integrate OIDC Authorization Code - In this flow, the user submits the credentials and grant access.
    • Integrate OIDC Implicit Code - Useful for trusted apps/service as the access token is included in the redirection.
    • Integrate OIDC Hybrid Flow - In this flow, some tokens are returned from the Authorization Endpoint and others are returned from the Token Endpoint. Applications that are able to securely store Client Secrets may benefit from the use of the Hybrid Flow which allows your application to have immediate access to an ID token.

References

For more information on the SDK, follow the reference guide CyberArk Identity Java SDK reference.

Claims decoded

The decoded value of id_token are claims. Now to get those call the static method claims passing the id_token.

JsonNode claims = OIDCClient.claims(YOUR_ACCESS_TOKEN);
{
  auth_time:1636960792,
  iss: "YOUR_TENANT_URL",
  exp: 1635872490,
  iat: 1635854490,
  DisplayName: "YOUR_DISPLAY_NAME",
  aud: "1b77bc96-315c-4abf-b194-dd67766e0315",
  email: "YOUR_EMAIL",
  unique_name: "YOUR_UNIQUE_NAME",
  sub: "c2c7bcc6-9560-44e0-8dff-5be221cd37ee",
  Username: "YOUR_USERNAME",
  scope: "openid email",
  email_verified:true
}

Get User Details using Access Token

Request the user information related to the access_token. Call execute() method to get the user details.

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID");
try
{
   UserInfo result = oidcClient.userInfo("YOUR_ACCESS_TOKEN").execute();
} 
catch (IdentityException e)
{
   logger.error("Exception occurred while executing revoke token request : ", ex);
   throw ex;
}
{
  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"
}

Revoke the token

To remove the validity of the access_token, use revokeToken method of the OIDCClient instance by passing access_token as a parameter.

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
VoidRequest request = oidcClient.revokeToken(YOUR_ACCESS_TOKEN);
try 
{
    request.execute();
} 
catch (IdentityException ex)
{
   logger.error("Exception occurred while executing revoke token request : ", ex);
   throw ex;
}

Refresh the token

After the access_token is expired, use refreshToken method of the OIDCClient instance by passing refreshToken as a parameter.

To get the refresh_token, make sure to enable Issue refresh tokens in the OIDC web application Tokens section.

OIDCClient oidcClient = new OIDCClient("YOUR_TENANT_URL", "YOUR_OIDC_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
TokenRequest tokenRequest = oidcClient.refreshToken(YOUR_REFRESH_TOKEN);
try 
{
    TokenHolder tokenHolder = tokenRequest.execute();
} 
catch (IdentityException ex)
{
    logger.error("Exception occurred while executing refresh token request : ", ex);
    throw ex;
}
{
  access_token: "YOUR_ACCESS_TOKEN",
  id_token: "YOUR_ID_TOKEN",
  expires_in: 18000,
  scope: "all",
  token_type: "Bearer"
}

Using the above steps, you should be able to enable OpenID Connect capabilities in your application.