Using the Authentication Token (Client Versus Server Token Handling)

Overview

A successful response to /SecurityAdvanceAuthentication contains an Auth element specifying an authentication token for use when invoking subsequent endpoints. The server generates this unique code, and your client application must store it. The token is used to grant the client authenticated access to resources ( CyberArk Identity endpoints) on behalf of the user. That is, the token provides the server with proof that each subsequent API call is being made on behalf of a user who has already been authenticated.

Client Versus Server Token Handling

Client-Based Apps

In web applications, including Postman, the browser might retain this code as a .ASPXAUTH cookie and automatically pass it along to the server. In this case you likely won't have to manually store or handle the cookie.

Note: some browsers have a setting that prevents them from accepting third-party settings. When enabled, CyberArk Identity is seen as third party, so the browser will likely block the cookie. To get around this, CyberArk Identity must be set as a trusted site.

Server-Based Apps

Since a cookie can't be stored in browser-side code for server-based apps, a server must store the token value unaltered, and then pass it as a bearer token in subsequent API requests. In this case you will create a new header in the web request for the next API call, called Authorization, and set its value to ‘Bearer ’. For example:

Authorization: Bearer 6936714B84F54...

In order to enable this functionality you must first add your website's DNS in the Admin Portal:

Navigate to Infrastructure > Settings > Authentication > Security Settings.
Click Add.
Enter your website's DNS and click Add.
Click Save.

These elements are shown in the following screenshot:

Token Lifespan

Overview

A token has a limited lifespan that is set on the admin portal as described below. Once a token expires it cannot be refreshed, so a new token must be acquired by performing the authentication process again. A token's lifespan can also be ended by Logging Out.

Specifying the Duration of the Token

An admin specifies how long an ASPXAUTH token is valid for once issued, by navigating to Core Services > Policies > Authentication Policies > CyberArk Identity and setting the Hours until Identity cookie expires field: