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?

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

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

Add the ".npmrc" file In the same directory as your package.json file.

@cyberark:registry=https://npm.pkg.github.com

(Optional) Navigate to Github -> Settings -> Developer settings -> Personal Access Token.
Click on Configure SSO -> Authorize (cyberark).

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

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

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:

tenantURL, applicationId and clientId parameters acts as meta-data behind the scenes.

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

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
}

Introduction

How to install?

Authentication Process

StartAuthentication ()

Syntax

Parameters

AnswerChallenge()

Syntax

Parameters

StartPoll()

Syntax

Parameters

TOTP Authentication

Register OATH TOTP using the QR scan option

Syntax

Required Parameters

Response

Verify the TOTP

Syntax

Required Parameters

Response

Change User's Password

Syntax

Parameters

Response

Get User Attributes

Syntax

Required Parameters

Response

Update User Profile

Syntax

Required Parameters

Response

Sign-up with Captcha

Syntax

Required Parameters

Response

Sign-up with Bearer Token

Syntax

Required Parameters

Response

Fetch OIDC Application details

GetWidgetAssociatedApp()

Syntax

Required Parameters

Response

GetOIDCAppDetails

Syntax

Required Parameters

Response

Instantiate OAuth client library

Build an Authorize URL

Required parameters

Authorize URL

Exchange authorization code for Access Token

Required parameters

Get Claims (Base64 Decoded access_token)

Required parameters

Response

Refreshing an Access Token

Required parameter

Introspect an Access Token

Required parameters

Response

Configure an OIDCClient instance

Get User Details using Access Token

Required parameters

Response

Revoke Token

Required parameters

Response

Logging Out

Required parameters

Response

Exchange authorization code for `Access Token`