Use ID tokens

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

Overview

ID tokens are JSON web tokens (JWT tokens) that contain claims about the end user's authentication by an authorization server.

ID tokens generally provides claims information to the client such that the client can validate the authentication of the user. Once the client gets the claims information from the ID token, and as long as the token has not expired, the client can share this ID token to provide userinfo to any downstream apps the client uses.

Structure

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

{
  "auth_time": 1661682509,
  "iss": "<tenant_url>/<application_id>/",
  "iat": 1661683317,
  "aud": "<client_id>",
  "unique_name": "<username>",
  "exp": 1661701317,
  "sub": "<user_uuid>",
  "nonce": "abc"
}

The following table describes the fields in the ID 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 ID token is intended for

client ID

exp

The expiration time on or after which the ID token must not be accepted for processing

The processing of this parameter requires that the current date/time must be 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 ID token and to mitigate replay attacks

The value is passed through unmodified from the authentication request to the ID token. If this is present in the ID 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

This structure excludes the scope 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. ID tokens could contain other claims that can be ignored.

Previously, the ID token generated by CyberArk Identity included the scope information and had the following structure:

{
  "auth_time": 1661682509,
  "iss": "<tenant_url>/<application_id>/",
  "iat": 1661683317,
  "aud": "<client_id>",
  "unique_name": "<username>",
  "exp": 1661701317,
"scope": "openid email profile user_detail", "sub": "<user_uuid>", "nonce": "abc" }

Validate an ID token

The client application must validate the ID tokens.

  • The ID 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 ID 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 below:

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 ID 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 ID tokens

For best practices for storing tokens, see Token storage.

Set token expiry

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

The default value is five hours.

  • If there are any security concerns, you can reduce the lifetime of the ID token. However, reducing the lifetime of the ID token may tamper with the user experience, as the user has to re-authenticate to generate a new ID token.

  • After an ID token has expired, you may want to renew it. To renew an ID token, you must re-authenticate the user using CyberArk Identity.

  • CyberArk Identity also supports the prompt=None parameter in the authorization request. With this parameter, the client can request a new token without user intervention. (Unless, of course, the user has not logged out from OpenID)

  • The expiry time in the ID token prevents replay attacks. If someone records traffic from the Auth server, they can use that recorded traffic to trick the client app into thinking they have a valid user identity. However, if the client checks the expiry date, it will see that it might be a replay attack.