CyberArk Identity Java SDK

Introduction

CyberArk Identity Java SDK provides an authorization framework that enables you to implement CyberArk's OAuth client and OpenID Connect client within your application.
Using this SDK, you can integrate with different grant flows of OAuth and OpenID Connect clients for authentication and authorization.
It also provides feasibility to create users to the CyberArk Identity cloud directory.

OAuth client

Configure OAuth client instance

Instantiate the OAuth client library with the OAuthClient object by providing the OAuth client application details that will allow your application to make authorized API requests.

You can create the OAuthClient object in any of the following ways:

  1. tenantURL, applicationId and clientId parameters acts as meta-data behind the scenes.
OAuthClient identityOAuthClient;
identityOAuthClient = new OAuthClient(tenantURL, appId, clientId);
  1. tenantURL, applicationId, clientId and clientSecret parameters acts as meta-data behind the scenes .

Use this constructor when refreshing or revoking an access token.

OAuthClient identityOAuthClient;
identityOAuthClient = new OAuthClient(tenantURL, appId, clientId, clientSecret);

Constructor parameters

Parameter

Description

Required

tenantURL

CyberArk Identity Application URL

yes

applicationId

Your OAuth client Application ID.
You can find this value at OAuth client Application Settings section.

yes

clientId

Your login username.

yes

clientSecret

Your login user password.

optional

Build an Authorize URL

Create an AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider. The redirectUri must be white-listed in the Redirect destinations section under General Usage section of OAuth client application.

Parameters can be added to the final URL by using the builder methods.
Call the build() method and get the Authorize URL.

AuthorizeUrlBuilder authorizeUrl(String redirectUri);

Required parameters

  • redirectUri - The URL that a user will be re-directed after successful authentication.
    It is required parameter and must be a valid URL.

Builder Methods

  • Below mentions the list of builder methods available for authorizeUrl method.
// Sets the scope value.
AuthorizeUrlBuilder setScope(String scope);

// Sets the response type value.
AuthorizeUrlBuilder setResponseType(String responseType);

// Sets the state value.
AuthorizeUrlBuilder setState(String state);

// Sets the code challenge value.
AuthorizeUrlBuilder setCodeChallenge(String codeChallenge);

// Sets the code challenge method value.
AuthorizeUrlBuilder setCodeChallengeMethod(String codeChallengeMethod);

// Adds an additional parameter to the authorize URL.
AuthorizeUrlBuilder addAdditionalParameter(String name, String value);

Exchange authorization code for Access Token

Creates a request to exchange the code previously obtained by calling the /authorize endpoint.
The redirect URI must be sent in the /authorize call.

Parameters can be added to the token request by using the builder methods.
Call the execute() method to get the tokens.

TokenRequest requestToken(String code, String redirectUri);

Required parameters

  • code - The code previously obtained by calling the /authorize endpoint.
  • redirectUri - The URL that a user is directed to after successful authentication.

Builder Methods

  • Below mentions the list of builder methods available for the requestToken method.
// Sets the client id.
TokenRequest setClientId(String clientId);

// Sets the client secret.
TokenRequest setClientSecret(String clientSecret);

// Sets the authorization code value.
TokenRequest setAuthorizationCode(String authorizationCode);

// Sets the redirectURI URL.
TokenRequest setRedirectURI(String redirectURI);

// Sets the code verifier value.
TokenRequest setCodeVerifier(String codeVerifier);

// Sets the grantType to authorization_code.
TokenRequest setGrantType(String grantType);

// Sets the scope value.
TokenRequest setScope(String scope);

// Adds an additional header to the Token Request.
TokenRequest addHeader(String name, String value);

Get the Access Token using Client Creds grant type

Creates a request to get the tokens using the Client Credentials grant type.

Parameters can be added to the token request by using the builder methods.
When ready, call the execute() method to get the tokens.

TokenRequest requestTokenWithClientCreds();

Builder Methods

  • Below mentions the list of builder methods available for requestTokenWithClientCreds method.
// Sets the client id.
TokenRequest setClientId(String clientId);

// Sets the client secret.
TokenRequest setClientSecret(String clientSecret);

// Sets the grantType to client_creds.
TokenRequest setGrantType(String grantType);

// Sets the scope value.
TokenRequest setScope(String scope);

Get Access Token using Password grant type

Creates a request to get the tokens using Client Credentials grant type.

Parameters can be added to the token request by using the builder methods.
When ready, call execute() method to get the tokens.

TokenRequest requestTokenWithPassword(String userName, String password);

Required parameters

  • userName - The login user name.
  • password - The login user password.

Builder Methods

  • Below mentions the list of builder methods available for requestTokenWithPassword method.
// Sets the login user name.
TokenRequest setUserName(String userName);

// Sets the login user password.
TokenRequest setPassword(String password);

// Sets the grantType to client_creds.
TokenRequest setGrantType(String grantType);

// Sets the scope value.
TokenRequest setScope(String scope);

Get Claims (Base64 Decoded access_token)

The Access Token is a security token that contains Claims (fields in token) about the user being authenticated. The Claims contains information such as the issuer, the expiration timestamp, subject identifier, nonce, and other fields depending on the scopes you requested.

JsonNode claims(String accessToken);

Required parameters

  • accessToken - The access_Token previously obtained by exchanging the authorization code.

Revoking an Access Token

Creates a request to revoke an existing access_token. Call execute() method to revoke the token.

VoidRequest revokeToken(String accessToken);

Required parameters

  • accessToken - The access_Token previously obtained in token request.

Builder Methods

  • Below mentions the list of builder methods available for the revokeToken method.
// Sets the client id.
VoidRequest setClientId(String clientId);

// Sets the client secret.
VoidRequest setClientSecret(String clientSecret);

// Sets the access token.
VoidRequest setAccessToken(String accessToken);

Refreshing an Access Token

Creates a request to refresh an access_token by exchanging the refresh_token, which was obtained by calling the /requestToken endpoint earlier. Call execute() method to refresh the token.

TokenRequest refreshToken(String refreshToken);

Required parameters

  • refreshToken - The refresh_token previously obtained in token request.

Builder Methods

  • Below mentions the list of builder methods available for the refreshToken method.
// Sets the client id.
VoidRequest setClientId(String clientId);

// Sets the client secret.
VoidRequest setClientSecret(String clientSecret);

// Sets the refresh token value.
TokenRequest setRefreshToken(String refreshToken);

// Sets the grantType to refresh_token.
TokenRequest setGrantType(String grantType);

Introspect an Access Token

Creates a request to introspect an existing access_token to get the token's status. Call execute() method to introspect the token.

GenericTokenRequest introspect(String accessToken);

Required parameters

  • accessToken - The access_Token previously obtained from the token request.

OIDC Client

Configure OIDC client instance

Configure the OIDCClient object by providing the OpenID Connect application details that will allow your application to make authorized API requests.

OIDCClient is inherited from OAuthClient class. So, All the above mentioned methods will be available as part of the OIDCClient instance.

You can create OIDCClient object in two ways:

  • With tenantURL, applicationId and clientId parameters that behind the scenes acts as meta-data.
OIDCClient identityOIDCClient;
identityOIDCClient = new OIDCClient(tenantURL, appId, clientId);
  • With tenantURL, applicationId, clientId and clientSecret parameters that behind the scenes acts as meta-data.

    Use this constructor when refreshing or revoking an access token.

OIDCClient identityOIDCClient;
identityOIDCClient = new OIDCClient(tenantURL, appId, clientId, clientSecret);

Constructor parameters

Parameter

Description

Required

tenantURL

CyberArk Identity Application URL

yes

applicationId

Your OpenID Connect Application ID. You can find this value in OpenID Connect Application Settings section.

yes

clientId

Your OpenID Connect Client ID. You can find this value at Identity Provider Configuration under the Trust section of the OpenID Connect Application.

yes

clientSecret

Your OpenID Connect Client Secret. You can find this value at Identity Provider Configuration under the Trust section of the OpenID Connect Application.

optional

Get User Details using Access Token

Create a request to get the user information associated with a given access_token. This will only work if the openid scope has granted the token. Call the execute() method to get the user details.

APIRequest<UserInfo> userInfo(String accessToken);

Required parameters

  • accessToken - The access_Token previously obtained by exchanging the authorization code.

User Management

Configure User Management Instance

Create a UserManagement object instance by providing the CyberArk Identity Application URL.

UserManagement userMgmt = new UserManagement(tenantURL);

Constructor parameters

Parameter

Description

Required

tenantURL

CyberArk Identity Application URL

yes

Sign-up with Captcha

Creates a Sign-up request to create a new user in the CyberArk Identity cloud directory by sending the Google Re-Captcha Token for verification.

Parameters can be added to the Sign-up request by using the builder methods.
When ready, call execute() method to get the Sign-up response.

SignUpRequest signUpWithCaptcha(String reCaptchaToken);

Required parameters

  • reCaptchaToken - the reCaptchaToken received from Google Re Captcha server.

Builder Methods

  • Below mentions the list of builder methods available for signUpWithCaptcha method.
// Sets the user name.
SignUpRequest setUserName(String userName);

// Sets the user password.
SignUpRequest setPassword(String password);

// Sets the user confirm password.
SignUpRequest setConfirmPassword(String confirmPassword);

// Sets the user email.
SignUpRequest setEmail(String emailId);

// Sets the user mobile number.
SignUpRequest setMobileNumber(String mobileNumber);

// Sets the additional attributes for the user. It takes key-value pairs as an input.
SignUpRequest setAdditionalAttributes(Map<String, Object> additionalAttributes);

Sign-up with Bearer Token

Creates a Sign-up request to create a user in the CyberArk Identity cloud directory by passing Bearer Token generated through OAuth Client Credentials flow as Authorization header.

Parameters can be added to the Sign-up request by using the builder methods.
When ready, call execute() method to get the Sign-up response.

SignUpRequest signUpWithBearerToken(String bearerToken);

Required parameters

  • bearerToken - the bearerToken generated through OAuth Client Credentials flow.

Builder Methods

  • Below mentions the list of builder methods available for signUpWithBearerToken method.
// Sets the user name.
SignUpRequest setUserName(String userName);

// Sets the user password.
SignUpRequest setPassword(String password);

// Sets the user confirm password.
SignUpRequest setConfirmPassword(String confirmPassword);

// Sets the user email.
SignUpRequest setEmail(String emailId);

// Sets the user mobile number.
SignUpRequest setMobileNumber(String mobileNumber);

// Sets the additional attributes for the user. It takes key-value pairs as an input.
SignUpRequest setAdditionalAttributes(Map<String, Object> additionalAttributes);

Update User Profile

Creates an update profile request to update the user details in the CyberArk Identity cloud directory by passing Bearer Token generated as part of the user authentication flow in the Authorization header.

SignUpRequest updateProfile(String bearerToken, userJson);

Required parameters

  • bearerToken - the bearerToken generated as part of the user authentication flow.
  • userJson - The user details as a JSON converted to a String

Builder methods

  • Below mentions the list of builder methods available for the updateProfile method.
// Sets the additional attributes for the user. It takes key-value pairs as an input.
SignUpRequest setAdditionalAttributes(Map<String, Object> additionalAttributes);

Authentication

Register OATH TOTP using the QR scan option

Get the QR code of OATH TOTP to enrol for the MFA factor. You need to pass the Bearer Token generated as part of authentication.

AuthRequst getTotpQr(String bearerToken);

Required parameters

  • bearerToken - the bearerToken generated as part of the user authentication flow.

Verify the TOTP

Verify the TOTP of the registered user authentication.

AuthRequest validateTotp(String bearerToken, String payloadJson)

Using the CyberArk Identity Java SDK, you can integrate and enable your java applications for a rich OAuth, OIDC authentication and authorization, as well as user management.