Use the CyberArk Identity JavaScript SDK

Overview

The CyberArk Identity JavaScript 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 OAuth and OpenID Connect clients with different grant flows for authentication and authorization.

Install the JavaScript SDK

  1. Create a PAT (personal access token) in your GitHub account.

    1. Go to Settings on Github.

    2. Go to Developer settings.

    3. Click the Personal Access Token item.

    4. Click Generate new token.

    5. Select repo and read:packages under the scopes section.

    6. Click Generate token.

  2. Open a terminal in the root folder location of your project.

    $ npm login --scope=@cyberark --registry=https://npm.pkg.github.com
    > Username: USERNAME
    > Password: TOKEN
    > Email: PUBLIC-EMAIL-ADDRESS
  3. Add the .npmrc file to the same directory as your package.json file.

    @cyberark:registry=https://npm.pkg.github.com
  4. (Optional) Navigate to Github > Settings > Developer settings > Personal Access Token.

    Select Configure SSO > Authorize (cyberark).

  5. (Optional) Click Continue to grant PAT access to the CyberArk organization.

  6. (Optional) Post PAT access to CyberArk, and then click Continue to the GitHub Personal Access Token page.

  7. Run this command in the terminal opened in step 2.

    $ npm install @cyberark/identity-js-sdk@latest

Run the authentication process

The basic authentication process is as follows: The client requests authentication for a user by calling StartAuthentication and passing enough information to identify the user and tenant.

Step 1: StartAuthentication ()

Start the authentication process by specifying a user, and then retrieve the authentication challenge(s) and subsequent mechanism(s) that the user must answer.

Syntax
startAuthentication(url, tenantID, username)
Parameters
* `url` - CyberArk Identity Application URL
* `tenantID` - Your CyberArk Identity Tenant ID
* `username` - login username

After the server receives the request, it validates the user and tenant ID specified in the body. It creates an MFA package response, which includes a session ID and an array of zero, one, or two authentication challenges for the client.

When your client receives this response, it must iterate through the challenges element. After the user submits the password, the client calls the AnswerChallenge() method.

Step 2: AnswerChallenge()

When the client sends the mechanismId and answer parameters, it initiates the following authentication process:

Syntax
answerChallenge (mechanismId ,answer)
Parameters
* mechanismId – challenge which will complete by the user for authentication
* tenantID - tenantId of the user

Step 3: StartPoll()

For out-of-bounds (OOB) mechanisms, it initiates polling.

The client can present a mechanism, such as a password, to the user. Once the user has entered the data, your client sends that to the server. A more involved mechanism is an out-of-bounds (OOB) challenge, which involves an additional entity in the authentication process.

For StartPoll, the mobile OTP is sent to the user's registered mobile phone for authentication, and email OTP is sent to the user's registered email address.

Syntax
startPoll (MechanismId, callback)
Parameters
* `MechanismId` -  As part of the `StartAuthentication` response, you will receive `MechanismId` based on the configured policy
* `callback` - Callback function on success or failure

Authenticate TOTP

Step 1: Register OATH TOTP using the QR scan option

Get the QR code of OATH TOTP to enroll for the MFA factor. You need to pass the bearer token generated as part of the authentication.

Syntax
getTotpQr(tenantUrl, access_token);
Required parameters

Parameter

Description

tenanturl

 

The CyberArk Identity application URL

access_token

 

The token obtained after successful authentication

Response
{
	"success":true,
	"Result":{
		"ProfileUuid":"f934e0c2-6bef-45ae-976c-d08ca61872f8",
		"Url":"otpauth://totp/testUser%40tenantSuffix?secret=IE4EERCCGM2MZWGZBTGNZRIJCTENKDG4YEIRCGIZBEKMKGGEYTENRU&issuer=testUser&digits=6&algorithm=SHA1&period=30&endpointUrl=https%3a%2f%2fyourTenant.my.idaptive.app%2fsecurity%2fSubmitOathOtpCode%3fuserUuid%3dc2c7bcc6-44e0-9560-8dff-5be221cd37ee",
		"UrlQr":"data:image/gif;base64,R0lGODlh+gD6APcAAAAAAAAAMwAAZgAAmQAAzAAA/wArAAArMwArZgArmQArzAAr/wBVAABVMwBVZgBVmQB"
	},
	"Message":null,
	"MessageID":null,
	"Exception":null,
	"ErrorID":null,
	"ErrorCode":null,
	"IsSoftError":false,
	"InnerExceptions":null
}

Step 2: Verify the TOTP

Verify the TOTP of the registered user authentication.

Syntax
validateTotp(tenantUrl, access_token, totpReq);
Required parameters

Parameter

Description

tenantUrl

 

The CyberArk Identity application URL

access_token

 

The token obtained after successful authentication

totpReq

 

The JSON object containing the profile uuid of user and the otp code to be validated * For example: { uuid: string = "", otpCode: string = ""}

Response
{
	success: true,
	Result: null,
	Message: null,
	MessageID: null,
	Exception: null,
	ErrorID: null,
	ErrorCode: null,
	IsSoftError: false,
	InnerExceptions: null
}

Change a user password

Use the changeUserPassword() function to update the password for a user who is authenticated.

Syntax
changeUserPassword(tenantUrl, authToken, oldPassword, newPassword);
Parameters

Parameter

Description

tenantUrl

 

The CyberArk Identity application UR

authToken

 

The token obtained after successful authentication

oldPassword

 

The user's current password

newPassword

 

The user's new password

Response

When the user’s password is changed, you get the success value as true.

{
	success: true,
	Result: null,
	Message: null,
	MessageID: null,
	Exception: null,
	ErrorID: null,
	ErrorCode: null,
	IsSoftError: false,
	InnerExceptions: null
}

When the oldpassword is incorrect, you get the success value as false.

{
	success: false,
	Result: null,
	Message: 'Password update failed. Please make sure the current password is correct.',
	MessageID: '_I18N_SetPasswordFailedWrongOldPassword'
}

Get user attributes

Create a request to get a user's attributes based on the user's UUID (unique id).

Syntax
userAttributes(tenantUrl,authToken,id);
Required parameters

Parameter

Description

tenantURL

 

The CyberArk Identity application URL

authToken

 

The token obtained after successful authentication

id

 

The user's UUID

Response

When the user passes the correct username or UUID, the response is as follows:

{
	"success":true,
	"Result":{
		"directoryServiceUuid":"09B9A9B0-6CE8-465F-AB03-65766D33B05E",
		"ForcePasswordChangeNext":"False",
		"DisplayName":"rushyanthgoru",
		"PictureUri":null,
		"CloudState":"None",
		"OrgPath":null,
		"InEverybodyRole":true,
		"OauthClient":false,
		"imageName":null,
		"MobileNumber":"+44 7911 123456",
		"LastModifiedDate":"/Date(1649861229784)/",
		"LastPasswordChangeDate":"/Date(1649826897207)/",
		"CreateDate":"/Date(1646019172250)/",
		"LockedByAdmin":false,
		"SubjectToCloudLocks":true,
		"Alias":"clouddev.test",
		"ReportsTo":"Unassigned",
		"Name":"rushyanthg@clouddev.test",
		"PreferredCulture":"",
		"Version":"1",
		"Mail":"Rushyantha.goru@clouddev.test",
		"Uuid":"f82682e6-bc3c-41bb-b236-7cbca3f9cb89",
		"State":"None"
	},
	"Message":null,
	"MessageID":null,
	"Exception":null,
	"ErrorID":null,
	"ErrorCode":null,
	"IsSoftError":false,
	"InnerExceptions":null
}

When the user passes the incorrect username or UUID, the response is as follows:

{
	"success":false,
	"Result":null,
	"Message":"User f82682e6-bc3c-41bb-b236-7cbca3f9c not found; they may have been deleted or the directory may be unavailable.",
	"MessageID":"_I18N_UserNotFound",
	"Exception":"CyberArkIdentity.Cloud.Core.UserNotFoundException: User f82682e6-bc3c-41bb-b236-7cbca3f9c not found; they may have been deleted or the directory may be unavailable.\r\n   at CyberArkIdentity.Cloud.Core.Controllers.UserMgmtController.<>c__DisplayClass57_0.<GetUserAttributes>b__0() in C:\\Code\\cloud\\Core\\Cloud\\Controllers\\UserMgmtController.cs:line 1948\r\n   at CyberArkIdentity.Cloud.Core.RestHelpers.JsonRest.StandardJsonResult(Func`1 action) in C:\\Code\\cloud\\Core\\Cloud\\RestHelpers\\JsonResponse.cs:line 388",
	"ErrorID":"1307a535-e009-4be2-b1ad-6ef2585ec6ce:88664f6493b1421eba4d7b5f09a7b67f",
	"ErrorCode":"404",
	"IsSoftError":false,
	"InnerExceptions":null
}

Update a user profile

This creates an update profile request to update the CyberArk Identity cloud directory user details passing the auth token generated as part of the user authentication flow.

Syntax
updateProfile(tenantUrl,userProfile,authToken);
Required Parameters

Parameters

Description

tenantUrl

 

The CyberArk Identity application URL

userProfile

 

The user details sent as a JSON object

For example: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}

authToken

 

The token obtained after successful authentication

Response

The success response is as follows:

{
	"success": true,
	"Result": null,
	"Message": null,
	"MessageID": null,
	"Exception": null,
	"ErrorID": null,
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

The failure response is as follows:

{
	"success": false,
	"Result": null,
	"Message": "User name is invalid; user names must be of the form 'name@suffix', not contain restricted characters, and suffix must match an existing User Service suffix.",
	"MessageID": "_I18N_InvalidCDSUserName",
	"ErrorID": "2535cd7f-1d1a-4535-a77e-2ea671ce3956:a1fe863a27c34756a9d8f6a93190f747",
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

Configure sign-up with CAPTCHA

This creates a sign-up request to create a new user in the CyberArk Identity cloud directory by sending the Google ReCAPTCHA token for verification.

Syntax
signUpWithCaptcha(tenantUrl,signup)
Required parameters

Parameters

Description

tenantUrl

 

The CyberArk Identity application URL

signup

 

The user details sent as a JSON object

For example:{Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:'',reCaptchaToken:''} reCaptchaToken - the reCAPTCHA token received from Google reCAPTCHA server

Response

When the user is created, the success value is true.

{
	"success": true,
	"Result": {
		"Auth": "AC108A4EEAC9255F0D991B907B982EB63FC495EF16F54C8F00FCA1D5F1483ECA8A5334869FCDFAA4A314CC84EAD3BB613D91F846708F03A25B70BC7096859E87A8B0EBA16CA390B3216829DD8D3F66F2B53A248659734A451AC2E7B5060AEB13641E14392A8FBD56DE3006F6CFADB15755DDCEE9BF3E2289B36F7CF3ABB37C4B7EA990F816034A60DB83364A1520C08E501D6E7EDCDE13A81E9FFEBFBECF6DE97999D0219F1A8EA0E56534410F8BC49FCC11E675A13131D63B75F360A55F948987E58604BAF3F112FB0AAEC346455D07EC664C736F07CBD11BDE500B10DAA726A9BFAE75B8529B8C51E53C25AE5F34941F1E33CC77212352ADF420C45D3EFE538953997CEBCD65E2D04D69C1A554AC68DD28D8163736D1C50A79F544E08B443867FD7F92074C6C03C722881274491428830BA0DD5E9FFDF32E6A0DECE1DD153D23BA1036D0275369A7896E277209294A17FFF366",
		"UserId": "46bb8b6a-693b-43cc-956c-962857e6ecd4"
	},
	"Message": null,
	"MessageID": null,
	"Exception": null,
	"ErrorID": null,
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

If the CAPTCHA validation fails during sign-up, the success value is false.

{
	"success": false,
	"Result": null,
	"Message": "Captcha validation failed",
	"MessageID": "_I18N_System.Exception",
	"Exception": "System.Exception: Captcha validation failed\r\n   at Identity.Cloud.Customer.Signup.SignupManager.SignupUsingCaptcha(DataEntity payload) in C:\\Code\\cloud\\Customer\\Cloud\\Signup\\SignupManager.cs:line 432\r\n   at Identity.Cloud.Customer.Controllers.UserController.<>c__DisplayClass12_0.<Signup>b__2() in C:\\Code\\cloud\\Customer\\Cloud\\controllers\\UserController.cs:line 264\r\n   at CyberArkIdentity.Cloud.Core.TenantContext.Switch(String newContext, UserToken userToken, Boolean userObjectRequired, Action action) in C:\\Code\\cloud\\Core\\Cloud\\TenantContext.cs:line 525\r\n   at CyberArkIdentity.Cloud.Core.TenantContext.Switch(String newContext, UserToken userToken, Action action) in C:\\Code\\cloud\\Core\\Cloud\\TenantContext.cs:line 511\r\n   at Identity.Cloud.Customer.Controllers.UserController.<Signup>b__12_0() in C:\\Code\\cloud\\Customer\\Cloud\\controllers\\UserController.cs:line 259\r\n   at CyberArkIdentity.Cloud.Core.RestHelpers.JsonRest.StandardJsonResult(Func`1 action) in C:\\Code\\cloud\\Core\\Cloud\\RestHelpers\\JsonResponse.cs:line 388",
	"ErrorID": "f4958e45-fd13-4589-9843-dc4b8e7e7624:b959b283bebb4e68a86a2f2a065d25df",
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

Configure sign-up with a bearer token

This creates a sign-up request to create a user in the CyberArk Identity cloud directory by passing a bearer token generated through the OAuth client credentials flow as an authorization header.

Syntax
signUpWithBearerToken(tenantUrl,signup,bearerToken)
Required Parameters

Parameters

Description

tenantUrl

The CyberArk Identity application URL

signup

The user details sent as a JSON object

For example: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}

bearerToken

A bearer token generated through the OAuth client credentials flow.

Response

When the user is created, the success value is true.

{
	"success": true,
	"Result": {
		"Auth": "AC108A4EEAC9255F0D991B907B982EB63FC495EF16F54C8F00FCA1D5F1483ECA8A5334869FCDFAA4A314CC84EAD3BB613D91F846708F03A25B70BC7096859E87A8B0EBA16CA390B3216829DD8D3F66F2B53A248659734A451AC2E7B5060AEB13641E14392A8FBD56DE3006F6CFADB15755DDCEE9BF3E2289B36F7CF3ABB37C4B7EA990F816034A60DB83364A1520C08E501D6E7EDCDE13A81E9FFEBFBECF6DE97999D0219F1A8EA0E56534410F8BC49FCC11E675A13131D63B75F360A55F948987E58604BAF3F112FB0AAEC346455D07EC664C736F07CBD11BDE500B10DAA726A9BFAE75B8529B8C51E53C25AE5F34941F1E33CC77212352ADF420C45D3EFE538953997CEBCD65E2D04D69C1A554AC68DD28D8163736D1C50A79F544E08B443867FD7F92074C6C03C722881274491428830BA0DD5E9FFDF32E6A0DECE1DD153D23BA1036D0275369A7896E277209294A17FFF366",
		"UserId": "46bb8b6a-693b-43cc-956c-962857e6ecd4"
	},
	"Message": null,
	"MessageID": null,
	"Exception": null,
	"ErrorID": null,
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

If the user already exists, the success value is false.

{
	"success": false,
	"Result": null,
	"Message": "User name user@clouddev.test is already in use.",
	"MessageID": "_I18N_DuplicateCDSUserName",
	"Exception": "CyberArkIdentity.Cloud.Core.DirectoryServices.DuplicateCDSUserNameException: User name rishi44@clouddev.test is already in use.\r\n   at CyberArkIdentity.Cloud.Core.DirectoryServices.CdsUserNamePolicy.ValidateNameAgainstPolicy(String name, String existingUserUuid, Boolean isFirstAdmin, Boolean skipDirectoryService, Boolean skipAliasCheck) in C:\\Code\\cloud\\Core\\Cloud\\DirectoryServices\\CyberArkIdentityDirectoryService\\CdsUserNamePolicy.cs:line 53\r\n   at CyberArkIdentity.Cloud.Core.DirectoryServices.CyberArkIdentityDirectoryService.MakeUserDE(String username, String password, Boolean firstUserAdmin, Boolean isInEverybodyRole, Boolean requirePasswordChange, String authSource, String emailAddr, Boolean skipDSNameCheck, Boolean skipPasswordValidation, Boolean skipAliasCheck, String displayName, String rowKey) in C:\\Code\\cloud\\Core\\Cloud\\DirectoryServices\\CyberArkIdentityDirectoryService\\CyberArkIdentityDirectoryService.cs:line 478\r\n   at CyberArkIdentity.Cloud.Core.DirectoryServices.CyberArkIdentityDirectoryService.MakeUserDE(String username, String password, Boolean firstUserAdmin, Boolean isInEverybodyRole, Boolean requirePasswordChange, String authSource, String emailAddr, Boolean skipDSNameCheck, Boolean skipPasswordValidation, Boolean skipAliasCheck, String displayName) in C:\\Code\\cloud\\Core\\Cloud\\DirectoryServices\\CyberArkIdentityDirectoryService\\CyberArkIdentityDirectoryService.cs:line 454\r\n   at CyberArkIdentity.Cloud.Core.DirectoryServices.CyberArkIdentityDirectoryService.CreateCloudUser(DataEntity args, Boolean sendEmailInviteDefaultValue) in C:\\Code\\cloud\\Core\\Cloud\\DirectoryServices\\CyberArkIdentityDirectoryService\\CyberArkIdentityDirectoryService.cs:line 1697\r\n   at CyberArkIdentity.Cloud.Core.DirectoryServices.CyberArkIdentityDirectoryService.CreateUserIncludingAttributes(DataEntity userinfo) in C:\\Code\\cloud\\Core\\Cloud\\DirectoryServices\\CyberArkIdentityDirectoryService\\CyberArkIdentityDirectoryService.cs:line 1751\r\n   at Identity.Cloud.Customer.Signup.SignupManager.Signup(DataEntity payload) in C:\\Code\\cloud\\Customer\\Cloud\\Signup\\SignupManager.cs:line 281\r\n   at Identity.Cloud.Customer.Controllers.UserController.<Signup>b__12_1() in C:\\Code\\cloud\\Customer\\Cloud\\controllers\\UserController.cs:line 286\r\n   at Identity.Cloud.Customer.Controllers.UserController.<>c__DisplayClass15_0.<StandardJsonResultWithPermissionCheck>b__0() in C:\\Code\\cloud\\Customer\\Cloud\\controllers\\UserController.cs:line 313\r\n   at CyberArkIdentity.Cloud.Core.RestHelpers.JsonRest.StandardJsonResult(Func`1 action) in C:\\Code\\cloud\\Core\\Cloud\\RestHelpers\\JsonResponse.cs:line 388",
	"ErrorID": "2d30f593-fb9b-4f69-a7b7-202b69f12836:ac540d806efc4824a6486dbc51e59837",
	"ErrorCode": null,
	"IsSoftError": false,
	"InnerExceptions": null
}

Fetch OIDC application details

You can fetch details for an OIDC application linked to a widget used for authentication.

Step 1: GetWidgetAssociatedApp()

Get the application key associated with a widget used for login/authentication.

Syntax
getWidgetAssociatedApp(tenantUrl, widgetId);
Required parameters

Parameter

Description

tenantUrl

 

The CyberArk Identity application URL

widgetId

 

The widget ID for which the application key is to be fetched

Response

The appKey of the associated application is returned on a successful request call.

"69e2b8f0-bc1c-4434-925e-048fe791515d"

If no application is linked with the widget, the request returns the following message:

"No application associated with the given widgetId"

If the widgetid provided is incorrect, the request returns the following failure response:

"Invalid widgetId"

Step 2: GetOIDCAppDetails

After obtaining the appKey for the application associated with a widget using the above method, pass it in the getOIDCAppDetails(tenantUrl, appKey, access_token) method to fetch the OIDC application details.

Syntax
getOIDCAppDetails(tenantUrl, appKey, access_token);
Required parameters

Parameters

Description

tenantUrl

 

The CyberArk Identity application URL

appKey

 

The OIDC application key

access_token

 

The token obtained after successful authentication

Response

When a valid OIDC appKey is passed, a successful response from this request looks as follows:

{
	"AppID":"OIDCapp",
	"ClientID":"59e2b8f0-bc1c-4434-925e-048fe791515d",
	"ClientSecret":"testPassword",
	"Redirects":[
		"https://identitydemo.acmeinc.com:4200/RedirectResource"
	],
	"Scopes":[
		"all",
		"temp"
		]
	}

If the provided appKey in the request is invalid or is not an OIDC application, the response is the following message:

"No OIDC application associated with the widget"

Instantiate the OAuth client library

You can instantiate the OAuth client library with the CyberArkIdentityOAuthClient object by providing the OAuth client application details that allow your application to make authorized API requests.

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

  • The tenantURL, applicationId, and clientId parameters act as metadata behind the scenes.

    const identityOAuthClient;
    identityOAuthClient = new CyberArkIdentityOAuthClient (tenantURL, appId, clientId);
  • The tenantURL, applicationId, clientId, and clientSecret parameters act as metadata behind the scenes.

    const identityOAuthClient;
    identityOAuthClient = new CyberArkIdentityOAuthClient (tenantURL, appId, clientId, clientSecret);

Constructor parameters

Parameter

Description

Required
tenantURL

 

The CyberArk Identity application URL

 

yes
applicationId

 

Your OAuth client application ID

You can find this value at the OAuth client Application Settings section

 

yes
clientId

 

Your login username

yes
clientSecret

 

Your login user password

optional

Build an authorize URL

You can create an AuthorizeUrlBuilder to authenticate the user with the CyberArk Identity provider. The redirectUri must be allow-listed in the Redirect destinations section under the General Usage section of OAuth client application. This method accepts additional parameters such as key-value pairs. For example: To pass the one-time auth token as a key-value pair, "AUTH" as a key and the one-time auth token as a value and additional parameters will append as a query string to the authorized URL.

identityOAuthClient.authorizeURL(redirectUri, scope, response_type, code_challenge = null, params= {})
Required parameters

Parameter

Description

Required

redirectUri

 

The redirect URL value to set

Yes

scope

 

The scope defined in the tenant

Yes

clientId

 

Your username

Yes

clientSecret

 

Your password

Yes

response_type

 

The code to get after success

Yes

params

 

It will accept additional parameters as key-value pairs

No

Authorize URL
https://YOUR_TENANT_URL/OAuth2/Authorize/YOUR_OAUTH_APPLICATION_ID?redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_USER_ID&client_secret=YOUR_USER_PASSWORD&scope=YOUR_SCOPE&response_type=code

Exchange an authorization code for an access token

Use the identityOAuthClient instance to use the code received in the previous step to get the access token.

This is applicable for the authorization code+PKCE flow.

identityOAuthClient.requestToken (grantType, codeVerifier, redirectUrl,authorizationCode, serviceUser, serviceUserPwd)
Required parameters

Parameter

Description

Required

grantType

 

One of the item based on the grant flow authorization_code client_credentials * password

Yes
codeVerifier

 

The codeVerifier used for the PKCE flow

Yes
redirectUrl

 

The redirectUrl pass when using the PKCE/Auth flow

Yes
authorizationCode

 

The code returned from the authorization URL

Yes
serviceUser

 

The username of the tenant

Yes
serviceUserPwd

 

The password of the tenant

Yes

After a successful API request, this returns the access token:

{
	access_token  : YOUR_ACCESS_TOKEN
	refresh_token : YOUR_REFRESH_TOKEN
	token_type      : Bearer
	scope         : all
	expires_in    : 18000
}

The failure response is as follows:

{
	"error": "invalid_grant",
	"error_description": "supplied code does not match known request"
}

Get claims (base64 decoded access_token)

The Access token is a security token that contains Claims (fields in the 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.

identityOAuthClient.claims(accessToken);
Required parameters
  • accessToken - The access_Token previously obtained by exchanging the authorization code.
Response

The response as follows:

{
	auth_time:    auth time
	iss:  tenant URL
	iat:  1642762285
	aud:  e5932bf4-3610-4f91-a4d9-6b0cdd023c12
	unique_name:  name of the user
	exp:  expired time
	sub:  ea5e3538-71ac-4b41-a0b7-c5b4a5b23f05
	scope:   all
}

Refresh an access token

Creates a request to get an access_token by using the existing refresh_token.

identityOAuthClient.refreshToken(refreshToken);
Required parameter
  • refreshToken - The refresh_token previously obtained in token request.

After successful request, a new access_token is received.

Introspect an access token

Creates a request to validate the jwt or opaque token by calling the introspect endpoint. Set the clientId and clientSecret parameters for authorization and pass the token as a parameter. The response contains the status active as true or false.

identityOAuthClient.introspect(token);
Required parameters
  • token - The token obtained in the OAuth token endpoint request for an authorization code. After a successful request to the introspect endpoint, the response is that active is either true or false.
Response

When the token is active, you get the active value as true.

{
	"active": true,
	"exp": 1643986198,
	"sub": "c2c7bcc6-9560-44e0-8dff-5be221cd37ee",
	"scope": "all"
}

When the token is expired, you get active value as false.

{
	"active": false
}

Configure an OIDCClient instance

Before you begin, set up the OIDC Client. For more details, see configure the custom OpenID Connect application.

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

OIDCClient is inherited from the OAuthClient class. So, all the above-mentioned methods are available as part of the OIDCClient instance.

const identityOIDCClient = new CyberArkIdentityOIDCClient (tenantURL, applicationId, clientId, clientSecret);
  • With tenantURL, applicationId, clientId, and clientSecret parameters that act as metadata behind the scenes.

Constructor parameters

Parameter

Description

Required

tenantURL

 

The CyberArk Identity application URL

yes
applicationId

 

Your OpenID Connect application ID

 

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

yes
clientId

 

Your OpenID Connect Client ID

You can find this value in the identity provider configuration under the Trust section of the OpenID Connect application.

yes
clientSecret

 

Your OpenID Connect Client Secret

You can find this value in the identity provider configuration under the Trust section of the OpenID Connect application.

optional

Get user details using an 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.

identityOIDCClient.userInfo(accessToken);
Required parameters
  • accessToken - The access_Token previously obtained in a token request.
Response

The accessToken response as follows:

{
	aud:  8f16a026-721c-4388-a98d-eeb066c1ba76
	sub:  ea5e3538-71ac-4b41-a0b7-c5b4a5b23f05
	unique_name:  chethan@clouddev.test
	email_verified    :true
	auth_time:    1642762721
	name: name of the user
	preferred_username:   domain name
	given_name:   username
	family_name:  username
	email:  emailId of the user
}

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

Revoke a token

Creates a request to revoke an existing access_Token or id_Token.

identityOIDCClient.revokeToken(accessToken);
Required parameters
  • accessToken - The access_Token previously obtained in a token request.
Response

The function return void.

Log out

At the end of a session, you can invoke logout() to log the user out, passing the authentication token acquired from the authentication in the header.

logout(tenantUrl, access_token);
Required parameters

Parameter

Description

tenantUrl

 

The CyberArk Identity application URL

access_token

 

The token obtained after successful authentication

Response

The function returns a standard JSON response with filed success as true or false, depending on whether the API call was successful and whether user was successfully logged out.

{
	success: true,
	Result: null,
	Message: null,
	MessageID: null,
	Exception: null,
	ErrorID: null,
	ErrorCode: null,
	IsSoftError: false,
	InnerExceptions: null
}