Identity Cloud

Introduction to sessions and cookies

Identity Cloud uses two types of tokens that represent an exchange of information, usually interactive, between Identity Cloud and a user or entity:

  • Authentication sessions, which Identity Cloud uses to manage authentication journeys before a user has authenticated successfully.

  • Sessions, which Identity Cloud creates after a user has authenticated successfully. Sessions let Identity Cloud manage the user’s or entity’s access to resources.

Sessions and cookies

Sessions require the user or client to be able to hold on to cookies.

Identity Cloud issues a cookie to the user or entity at the beginning of an authentication journey. This cookie corresponds to an authentication session.

Identity Cloud issues another cookie to the user or entity after successful authentication. This cookie corresponds to a session.

The content in these cookies differs depending on the session type and location.

Session location

Both authentication sessions and sessions can be stored on the client or on the server.

Sessions stored on the server are called server-side sessions. Server-side sessions are stored in a database internal to Identity Cloud called the Core Token Service (CTS) token store.

Sessions stored on the client are called client-side sessions. Client-side sessions are stored in the session cookie.

Regardless of the session location, Identity Cloud issues a cookie to the user or entity; however, the content in the session cookies differs depending on the session’s location:

  • Server-side sessions contain a reference to the session’s location in the CTS token store and several other pieces of information. The details about server-side sessions are maintained in the CTS token store.

  • Client-side session cookies contain all the details about the session.

Because server-side sessions only contain references to the locations where the session details are stored, while client-side cookies contain all the details about sessions, client-side session cookies are significantly larger than server-side session cookies.

Session location is configurable by realm. The following table illustrates where Identity Cloud can store sessions:

Table 1. Session storage location
In the CTS token store On the client

Authentication sessions

✔ (Default)


✔ (Default)

Session storage location can differ per realm, to suit specific realm requirements.

For more information about configuring session locations, refer to:

Identity Cloud provides a unique, pseudo-random session cookie name for each tenant. It is used in HTTP header values in Identity Cloud API requests; for example, in the OAuth 2.0 authorization grant flow.

You can change the value of your tenant’s cookie name. You might want to do this for these reasons:

  • You want to integrate a legacy system into Identity Cloud, and it expects to ingest a specific cookie name.

  • You want to set the cookie name to a format preferred by your company.

  1. In the Identity Cloud admin UI, open the Tenant menu (upper right).

  2. Select Tenant Settings.

  3. Select Global Settings.

  4. (Optional) View or copy the Cookie field value.

  5. Click Cookie.

  6. In the Cookie page:

    • To change the cookie name, modify the name in the CookieName field. Invalid values for the cookie name are iPlanetDirectoryPro and Prefix__HOST.

    • To set the cookie name to its default name, click Reset to Default.

    Changing the cookie name will invalidate all user sessions in the tenant.
  7. Click Save.

Throughout this documentation, the tenant session cookie name is referred to as <session-cookie-name>.

Authentication session allowlist

Authentication session allowlisting is an optional feature that maintains a list of in-progress authentication sessions and their progress in the authentication flow to protect against replay attacks.

When authentication session allowlisting is enabled, Identity Cloud generates a key-value pair for each authentication session and stores it for the length of the authentication flow in the following ways:

  • For client-side authentication sessions, Identity Cloud stores the key-value pair in the CTS token store.

  • For server-side authentication sessions, Identity Cloud creates the key-value pair as a session property in the authentication session.

Each time the authentication flow reaches an authentication node, Identity Cloud modifies the value of the stored key-value pair and sends it to the user or client that it is authenticating. The next request to Identity Cloud to continue the authentication flow must contain the key-value pair and must match the value expected by Identity Cloud.

If the authenticating user or client cannot provide the key-value pair with the values Identity Cloud expects, Identity Cloud would not continue the authentication flow, therefore protecting the authentication flow against malicious users wanting to rewind the authentication flow to a previous node.

For more information about the allowlisting setting, refer to Trees.

Configure authentication session allowlisting

  1. In the Identity Cloud admin UI, select Native Consoles > Access Management.

  2. Go to Realms > Realm Name > Authentication > Settings > Trees.

  3. Choose Enable Allowlisting.

  4. Click Save Changes.

Copyright © 2010-2024 ForgeRock, all rights reserved.