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
-
Create a PAT (personal access token) in your GitHub account.
-
Go to Settings on Github.
-
Go to Developer settings.
-
Click the Personal Access Token item.
-
Click Generate new token.
-
Select repo and read:packages under the scopes section.
-
Click Generate token.
-
-
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
-
Add the .npmrc file to 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.
Select Configure SSO > Authorize (cyberark).
-
(Optional) Click Continue to grant PAT access to the CyberArk organization.
-
(Optional) Post PAT access to CyberArk, and then click Continue to the GitHub Personal Access Token page.
-
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: |
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: |
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 |
---|---|
|
The CyberArk Identity application URL |
|
The user details sent as a JSON object For example: |
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 |
---|---|
|
The CyberArk Identity application URL |
|
The user details sent as a JSON object For example: |
|
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
, andclientId
parameters act as metadata behind the scenes.const identityOAuthClient; identityOAuthClient = new CyberArkIdentityOAuthClient (tenantURL, appId, clientId);
-
The
tenantURL
,applicationId
,clientId
, andclientSecret
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 thatactive
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
, andclientSecret
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
}