CyberArk Identity Java SDK

Introduction

CyberArk Identity Java SDK provides an authorization framework which 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 client for authentication and authorization.

Instantiate OAuth client library

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.
When ready, call 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 the one sent in the /authorize call.

Parameters can be added to the token request by using the builder methods.
When ready, call 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 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 Access Token using Client Creds 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 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 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 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);

Configure an OIDCClient instance

Configure 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 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 at OpenID Connect Application Settings section.

yes

clientId

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

yes

clientSecret

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

optional

Get User Details using Access Token

Create a request to get the user information associated to a given access_token. This will only work if the token has been granted by the openid scope. Call 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.

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