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
ParameterDescription
tenanturlCyberArk Identity Application URL
access_tokenToken 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
ParameterDescription
tenantUrlCyberArk Identity Application URL
access_tokenToken obtained after successful authentication
totpReqJSON 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
ParameterDescription
tenantUrlCyberArk Identity Application URL
authTokenToken obtained after successful authentication
oldPasswordUser's current password
newPasswordUser'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
ParameterDescription
tenantURLCyberArk Identity Application URL
authTokenToken obtained after successful authentication
idUser'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
ParametersDescription
tenantUrlCyberArk Identity Application URL
userProfileThe user details sent as a JSON object
Ex: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}
authTokenToken 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
ParametersDescription
tenantUrlCyberArk Identity Application URL
signupThe 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
ParametersDescription
tenantUrlCyberArk Identity Application URL
signupThe user details sent as a JSON object
Ex: {ID:'',Name:'',HomeNumber:'',MobileNumber:'',DisplayName:'',Mail:''}
bearerTokenBearerToken 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
ParameterDescription
tenantUrlCyberArk Identity Application URL
widgetIdWidget 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
ParametersDescription
tenantUrlCyberArk Identity Application URL
appKeyOIDC application key
access_tokenToken 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

ParameterDescriptionRequired
tenantURLCyberArk Identity Application URLyes
applicationIdYour OAuth client Application ID.
You can find this value at OAuth client Application Settings section.
yes
clientIdYour login username.yes
clientSecretYour 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
ParameterDescriptionRequired
redirectUriThe redirect url value to setYes
scopeScope defines in the tenantYes
clientIdYour usernameYes
clientSecretYour passwordYes
response_typeCode will get after successYes
paramsit will accept additional parameters as key-value pairsNo
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
ParameterDescriptionRequired
grantTypeOne of the item based on the grant flow
authorization_code
client_credentials
* password
Yes
codeVerifiercodeVerifier used for PKCE flowYes
redirectUrlredirectUrl pass when using PKCE/Auth flowYes
authorizationCodethe code returned from authorization URLYes
serviceUserUsername of the tenantYes
serviceUserPwdPassword of the tenantYes

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

ParameterDescriptionRequired
tenantURLCyberArk Identity Application URLyes
applicationIdYour OpenID Connect Application ID. You can find this value at OpenID Connect Application Settings section.yes
clientIdYour OpenID Connect Client ID. You can find this value at Identity Provider Configuration under Trust section of OpenID Connect Application.yes
clientSecretYour 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
ParameterDescription
tenantUrlCyberArk Identity Application URL
access_tokenToken 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
}