CyberArk Identity JavaScript SDK

Introduction

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.

How to install?

  1. Create a PAT(Personal Access Token) in your GitHub account.
    1.1 Go to Settings on Github
    1.2 Go to Developer settings
    1.3 Click the Personal Access Token item
    1.4 Click Generate new token
    1.5 Select repo and read:packages under scopes section
    1.6 Click Generate token
15021502

Personal Access token in GitHub

  1. Open a terminal in the root folder location of your project.
$ npm login [email protected] --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS
  1. Add the ".npmrc" file In the same directory as your package.json file.
@cyberark:registry=https://npm.pkg.github.com
  1. (Optional) Navigate to Github -> Settings -> Developer settings -> Personal Access Token.
    Click on Configure SSO -> Authorize (cyberark).
16231623
  1. (Optional) Click on Continue to grant PAT access to the CyberArk organization.
602602
  1. (Optional) Post PAT access to CyberArk, click on the Continue to GitHub Personal Access Token page.
591591
  1. Execute this command in the terminal opened in step 2.
$ npm install @cyberark/[email protected]

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.

StartAuthentication ()

Start the authentication process by specifying a user, 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 all the Challenges elements.
After the user submits the password, the client calls the AnswerChallenge() method.

AnswerChallenge()

When the client sends the mechanismId and answer, it will initiate the following authentication process.

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

StartPoll()

For Out of bounds(OOB) mechanisms, It will initiate polling.

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

Example: To use StartPoll, the mobile OTP will be sent to the user's registered mobile phone for authentication, and email OTP will be 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

TOTP Authentication

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 authentication.

Syntax
getTotpQr(tenantUrl, access_token);
Required Parameters

Parameter

Description

tenanturl

CyberArk Identity Application URL

access_token

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
}

Verify the TOTP

Verify the TOTP of the registered user authentication.

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

Parameter

Description

tenantUrl

CyberArk Identity Application URL

access_token

Token obtained after successful authentication

totpReq

JSON object containing the profile uuid of user and the otp code to be validated

  • Eg: { uuid: string = "", otpCode: string = ""}
Response
{
  success: true,
  Result: null,
  Message: null,
  MessageID: null,
  Exception: null,
  ErrorID: null,
  ErrorCode: null,
  IsSoftError: false,
  InnerExceptions: null
}

Change User's Password

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

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

Parameter

Description

tenantUrl

CyberArk Identity Application URL

authToken

Token obtained after successful authentication

oldPassword

User's current password

newPassword

User's new password

Response

When the user’s password is changed, you will 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 will 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/info based on the user's UUID (unique id).

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

Parameter

Description

tenantURL

CyberArk Identity Application URL

authToken

Token obtained after successful authentication

id

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":"[email protected]",
      "PreferredCulture":"",
      "Version":"1",
      "Mail":"[email protected]",
      "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 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

CyberArk Identity Application URL

userProfile

The user details sent as a JSON object
Ex: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}

authToken

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 as follows

{
  "success": false,
  "Result": null,
  "Message": "User name is invalid; user names must be of the form '[email protected]', 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
}

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.

Syntax
signUpWithCaptcha(tenantUrl,signup)
Required Parameters

Parameters

Description

tenantUrl

CyberArk Identity Application URL

signup

The user details sent as a JSON object
Ex:{Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:'',reCaptchaToken:''}

reCaptchaToken - the reCaptchaToken received from Google Re Captcha server.

Response

When the user gets created, you will get 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 is failed during signup, you will get 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
}

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.

Syntax
signUpWithBearerToken(tenantUrl,signup,bearerToken)
Required Parameters

Parameters

Description

tenantUrl

CyberArk Identity Application URL

signup

The user details sent as a JSON object
Ex: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}

bearerToken

BearerToken generated through OAuth Client Credentials flow.

Response

When the user gets created, you will get 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
}

When the user has already existed, you will get the success value is false.

{
  "success": false,
  "Result": null,
  "Message": "User name [email protected] is already in use.",
  "MessageID": "_I18N_DuplicateCDSUserName",
  "Exception": "CyberArkIdentity.Cloud.Core.DirectoryServices.DuplicateCDSUserNameException: User name [email protected] 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

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

GetWidgetAssociatedApp()

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

Syntax
getWidgetAssociatedApp(tenantUrl, widgetId);
Required Parameters

Parameter

Description

tenantUrl

CyberArk Identity Application URL

widgetId

Widget Id for which 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, it returns the below message in response.

"No application associated with the given widgetId"

Also, if the given widgetid provided is incorrect, the request would return below failure response.

"Invalid widgetId"

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 OIDC application details.

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

Parameters

Description

tenantUrl

CyberArk Identity Application URL

appKey

OIDC application key

access_token

Token obtained after successful authentication.

Response

The successful response from this request looks like the below when a valid OIDC appKey is passed.

{
   "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 would be a message.

"No OIDC application associated with the widget"

Instantiate OAuth client library

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:

  1. tenantURL, applicationId and clientId parameters acts as meta-data behind the scenes.
const identityOAuthClient;
identityOAuthClient = new CyberArkIdentityOAuthClient (tenantURL, appId, clientId);
  1. tenantURL, applicationId, clientId and clientSecret parameters acts as meta-data behind the scenes.
const identityOAuthClient;
identityOAuthClient = new CyberArkIdentityOAuthClient (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.
This method will accept additional parameters like 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

Scope defines in the tenant

Yes

clientId

Your username

Yes

clientSecret

Your password

Yes

response_type

Code will 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 authorization code for Access Token

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

It is applicable for 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

codeVerifier used for PKCE flow

Yes

redirectUrl

redirectUrl pass when using PKCE/Auth flow

Yes

authorizationCode

the code returned from authorization URL

Yes

serviceUser

Username of the tenant

Yes

serviceUserPwd

Password of the tenant

Yes

After successful API request, it will return the access token.

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

The failure response 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 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
}

Refreshing 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, it will get new access_token.

Introspect an Access Token

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

identityOAuthClient.introspect(token);
Required parameters
  • token - The token obtained in OAuth token endpoint request an Authorization code.
    After the successful request of introspect endpoint, it will give the response active is true or false.
Response

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

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

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

{
   "active": false
}

Configure an OIDCClient instance

Note: Before you started, Refer link for setting up the OIDC Client
Configure the custom OpenID Connect application

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.

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

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.

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

Then accessToken response as follows.

{
  aud:  8f16a026-721c-4388-a98d-eeb066c1ba76
  sub:  ea5e3538-71ac-4b41-a0b7-c5b4a5b23f05
  unique_name:  [email protected]
  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 a rich OAuth and OIDC authentication and authorization.

Revoke 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 token request.
Response

The function return void.

Logging 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

CyberArk Identity Application URL

access_token

Token obtained after successful authentication

Response

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

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