CyberArk Identity Java SDK OAuth 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 OAuth Client Application in your tenant.
  • 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>OAuth</artifactId>
            <scope>system</scope>
            <version>1.0-SNAPSHOT</version>
            <systemPath>${project.basedir}/libs/Authorization-1.0-SNAPSHOT.jar</systemPath>
</dependency>

Introduction

Why this SDK?

This SDK provides an integration with CyberArk Identity OAuth client in 10 minutes which brings the ease of managing users. At the end of this guide, your java server integrates with CyberArk Identity OAuth Client for authentication and authorization.

Configure an OAuthClient instance using JAVA SDK

  • Import the SDK as specified in the Before you get started section
  • Create OAuthClient instance by passing the required parameters based on the flow you wish to use.
// import
import com.cyberark.client.OAuthClient;

// usage 1
OAuthClient oauthClient = new OAuthClient(YOUR_TENANT_URL, YOUR_OAUTH_APPLICATION_ID, YOUR_USER_ID);

// usage 2
OAuthClient oauthClient = new OAuthClient(YOUR_TENANT_URL, YOUR_OAUTH_APPLICATION_ID, YOUR_USER_ID, YOUR_CLIENT_SECRET);

References

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

Claims decoded

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

JsonNode claims = OAuthClient.claims(YOUR_ACCESS_TOKEN);
{
  aud: "70a9996f-6131-4158-86ec-e17931c3407d",
  auth_time: 1635854023,
  exp: 1635872490,
  iat: 1635854490,
  iss: "YOUR_TENANT_URL",
  scope: "all",
  sub: "c2c7bcc6-9560-44e0-8dff-5be221cd37ee",
  unique_name: "YOUR_UNIQUE_NAME"
}

Revoke the token

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

OAuthClient oauthClient = new OAuthClient("YOUR_TENANT_URL", "YOUR_OAUTH_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
VoidRequest request = oauthClient.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 OAuthClient instance by passing refreshToken as a parameter.

To get the refresh_token, make sure to enable Issue refresh tokens in the OAuth client setup. Refer here

OAuthClient oauthClient = new OAuthClient("YOUR_TENANT_URL", "YOUR_OAUTH_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
TokenRequest tokenRequest = oauthClient.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",
  expires_in: 18000,
  scope: "all",
  token_type: "Bearer"
}

Introspect an Access Token

Validate an access_token using introspect method of the OAuthClient instance by passing access_token as a parameter.

It returns JsonNode as a result which holds token's active status.

OAuthClient auth = new OAuthClient("https://example.my.idaptive.app/", "YOUR_APP_ID", "YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

try 
{
     JsonNode result = (JsonNode) auth.introspect("YOUR_ACCESS_TOKEN")
                              .execute();
} 
catch (IdentityException e) {
    logger.error("Exception occurred while introspecting an access token: ", ex);
    throw ex;
}
{      
  "active": true,      
  "exp": 1643991873,      
  "sub": "c2c7bcc6-9560-44e0-8dff-5be221cd37ee",      
  "scope": "all" 
}

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