Use access tokens

This topic describes how to use and manage OpenID Connect (OIDC) access tokens.

Overview

Access tokens are credentials that are used to access protected resources. They are used in token-based authentication to allow access to a set of APIs. Access tokens can be opaque or JWT tokens. By default, CyberArk Identity supports JWT access tokens in the OpenID Connect application.

Once the user is authenticated, the client application sends a request to CyberArk Identity for access tokens. The access token is sent as a bearer token for the subsequent API calls. You can use scopes to limit access to the CyberArk Identity APIs or to custom app APIs.

Structure

The access token generated by CyberArk Identity has the following structure:

{
  "auth_time": 1661741241,
  "iss": "{tenant_url}/{application_id}/",
  "iat": 1661747156,
  "aud": "<client_id>",
  "unique_name": "<username>",
  "exp": 1661765156,
  "sub": "<user_uuid>",
  "nonce": "abc",
  "scope": "<scope>"

The following table describes the fields in the access token:

Field	Description	Value
`iss`	The issuer identifier for the issuer of the response The `iss` value is a case-sensitive URL using the HTTPS scheme that contains scheme, host, and, optionally, port number and path components, and no query or fragment components.	https://<tenant_url>/<application_id>
`sub`	The subject identifier A locally unique and never-reassigned identifier within the issuer for the end user, which is intended to be consumed by the client	User UUID
`auth_time`	The time when the end user authentication occurred
`iat`	The time at which the JWT was issued
`aud`	The audience(s) that this access token is intended for	client ID
`exp`	The expiration time on or after which the access token must not be accepted for processing The processing of this parameter requires that the current date/time is before the expiration date/time listed in the value.
`unique_name`	The unique name for the authenticated user
`nonce`	The string value is used to associate a client session with an access token and to mitigate replay attacks. The value is passed through unmodified from the authentication request to the access token. If this is present in the access token, clients must verify that the nonce claim value equals the value of the nonce parameter sent in the authentication request.	The value passed by the client in the authorization request
`scope`	The scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account.

This structure excludes the claims details, based on the OIDC standards, when you select the Generate access and ID tokens with new structure (recommended) checkbox on the Token tab of the custom OpenID Connect application.

Previously, the access token generated by CyberArk Identity included claim details such as given_name, preferred_username, unique_name, and email_verified. The access token had the following structure:

{
  "auth_time": 1661741241,
  "iss": "{tenant_url}/{application_id}/",

  "given_name": "devadmin",
  "iat": 1661747156,
  "aud": "<client_id>",
  "email": "dev@clouddev.test",
  "preferred_username":"dev@clouddev.test",
  "unique_name": "<username>",
  "exp": 1661765156,
  "sub": "<user_uuid>",
  "nonce": "abc",
  "scope": "<scope>",
  "email_verified": true

Validate an access token

An access token is meant to be used for API calls. Once the client application receives the access token, the following verifications can be done:

The access token generated by CyberArk Identity is a JWT token encrypted using the "RS256" algorithm. This value can be found in the id_token_signed_response_alg parameter that can be found in the metadata of the OIDC app. The client must validate the signature of the access token according to JWS using the algorithm specified in the JWT alg header parameter.
The client must use the JWT keys provided by the issuer. The JWT keys are shared with the client using the metadata URL. The client can request the keys by sending an API call as follows:

POST {tenant_url}/OAuth2/Keys/{application_id}

The issuer identifier for the OpenID provider (typically obtained during discovery) must match the iss (issuer) claim's value.
The client must validate that the aud (audience) claim contains its client_id value registered at the issuer.
The current time must be before the time represented by the exp claim.
The iat claim can be used to reject tokens issued too far away from the current time, limiting the amount of time that nonces need to be stored to prevent attacks. The acceptable range is client-specific.
If a nonce value was sent in the authentication request, a nonce claim must be present, and its value checked to verify that it is the same value as the one sent in the authentication request. The client should check the nonce value for replay attacks. The precise method for detecting replay attacks is client-specific.
The client should check the auth_time claim value and request re-authentication if it determines that too much time has elapsed since the end-user authentication.

The client can also check if the access token is still valid, by making either of the following requests to CyberArk Identity:

Use the /OAuth2/Introspect endpoint to get the token's active status
Use the /Security/whoami endpoint passing the code as a bearer in the authorization header. The Result field in the response contains information about the user authorized on the tenant using the specified token, which implies that the token is valid.

Store access tokens

For best practices for storing tokens, see Token storage.

Set token expiry

You can set the expiry of an access token on the OIDC custom app as shown below:

The default value is five hours.

It is recommended to have short-lived access tokens (the recommended value is five minutes). To renew the access tokens, you must re-authenticate the user using CyberArk Identity or the refresh token to get a new access token without re-authenticating the user.