ID tokens

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

Structure of ID token

The ID token generated by CyberArk Identity has the below 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 fields of the ID token can be described as below:

Field	Description	Value
iss	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	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	Time at which the JWT was issued
aud	Audience(s) that this ID Token is intended for.	client ID
exp	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	unique_name The unique name for the authenticated user.
nonce	String value 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 present in the ID Token, Clients must verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request.	The value passed by the client in the authorization request

Note: ID Tokens may contain other claims. Any claims used that are not understood should be ignored.

ID token validation

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 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.

Storing ID tokens

The most secure way to store the ID tokens is on the server side for web applications and SPAs. The problem with this approach is SSO will not be supported, and the user needs to re-authenticate every time.

Another possible approach would be to store the ID tokens as a cookie using the set cookie. Issues with this approach are XSS attacks and CSRF attacks.

In XSS attacks, the client-side JS can read the cookies. This can be mitigated by setting the cookie as httpOnly cookie.
In CSRF attacks, the cookies are sent to the attackers. This type of attack can be mitigated using CORS policy, X-CSRF-TOKEN, or the same site cookie.

Storing the ID token in local or session storage is prone to XSS attacks. Besides, any data in sessionStorage is erased when a tab or a window is closed, so the user will have to log in every time to close and reopen tabs or the browser window.

For native mobile apps, store tokens in the OS's secure storage and limit access to that storage. For example, leverage KeyStore for Android and KeyChain for iOS.

👍
CyberArk Identity SDKs to store tokens
CyberArk Identity Android and iOS SDKs provide methods to store tokens in secure storage. Please find the links below to store tokens:

ID token expiry

The admin can set the ID token expiry on the OIDC custom app as below:

The default value is 5 hours.

If there are any security concerns, the lifetime of the ID token can be reduced. But 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 your ID token. To renew the ID token, you must re-authenticate the user using CyberArk Identity.