These topics cover concepts and implementation procedures to manage sessions in your AM environment.

This information is written for administrators configuring AM’s authentication and authorization components.

AM uses two types of tokens that represent an exchange of information, usually interactive, between AM and a user or identity:

AM session-related services are stateless unless otherwise indicated. They don’t hold any session information local to the AM instances.

Instead, they store session information either in the CTS token store (server-side sessions) or on the client (client-side sessions).

Server-side sessions reside in the CTS token store and can be cached in memory on one or more AM servers to improve system performance.

If the session request is redirected to an AM server that doesn’t have the session cached, that server must retrieve the session from the CTS token store.

AM stores server-side sessions in the CTS token store and caches sessions in server memory. If a server with cached sessions fails, or if the load balancer in front of AM servers directs a request to a server that doesn’t have the session cached, the AM server retrieves the session from the CTS token store, incurring performance overhead.

AM sends a reference to the session to the client, but the reference doesn’t contain any of the session state information. AM can modify a session during its lifetime without changing the client’s reference to the session.

By default, AM configures the CTS token store schema in the AM configuration store. Before configuring your AM deployment to use server-side journey or authenticated sessions, we recommend you install and configure an external CTS token store. Learn more in Core Token Service (CTS).

Server-side journey and authenticated sessions benefit from configuring sticky load balancing. Learn more in Load balancing.

For client-side sessions, AM returns the session state to the client after each request and requires the session state to be passed in with the subsequent request.

For security reasons, you should configure AM to sign and/or encrypt client-side journey and authenticated sessions. Decrypting and verifying the session can be an expensive operation to perform on each request. AM therefore caches the decrypt sequence in memory to improve performance.

Find information about configuring client-side security in Client-side session security.

Client-side sessions require additional setup in your environment to keep the sessions safe, and to ensure both the browser and the web server where AM runs can manage large cookies. Additionally, some AM features can’t be used with client-side sessions. Review the following list before configuring client-side sessions:

In-memory sessions reside in AM’s memory. AM sends clients a reference to the session, but the reference doesn’t contain any of the session state information.

Follow these steps to store journey sessions in AM’s memory:

AM manages active sessions, allowing single sign-on when authenticated users attempt to access system resources in AM’s control.

Authenticated sessions are terminated when a configured timeout is reached or when a user performs actions that cause session termination. Session termination effectively logs the user out of all systems protected by AM.

With server-side authenticated sessions, AM terminates sessions in four situations:

Under these circumstances, AM responds by removing server-side authenticated sessions from the CTS token store and from AM server memory caches. With the authenticated session no longer present in CTS, AM forces the user to reauthenticate during subsequent attempts to access protected resources.

When a user explicitly logs out of AM, AM also attempts to invalidate the iPlanetDirectoryPro cookie in users' browsers by sending a Set-Cookie header with an invalid session ID and a cookie expiration time that’s in the past. In the case of administrator session termination and session timeout, AM can’t invalidate the iPlanetDirectoryPro cookie until the next time the user accesses AM.

Session termination differs for client-side authenticated sessions. Since client-side authenticated sessions aren’t maintained in the CTS token store, administrators can’t monitor or terminate them. Because AM doesn’t modify the iPlanetDirectoryPro cookie for client-side sessions after authentication, the session idle time isn’t maintained in the cookie. Therefore, AM doesn’t automatically terminate client-side authenticated sessions that have exceeded the idle timeout.

Find information about tracking idle time in PingGateway in AmSessionIdleTimeoutFilter.

As with server-side authenticated sessions, AM attempts to invalidate the iPlanetDirectoryPro cookie from a user’s browser when the user logs out. When the maximum session time is exceeded, AM also attempts to invalidate the iPlanetDirectoryPro cookie in the user’s browser the next time the user accesses AM.

It’s important to understand that AM can’t guarantee cookie invalidation. For example, the HTTP response containing the Set-Cookie header might be lost. This isn’t an issue for server-side sessions, because a logged-out session no longer exists in the CTS token store, and a user who attempts to access AM after previously logging out will be forced to reauthenticate.

However, without the guarantee of cookie invalidation, deployments with client-side sessions can experience issues. For example, a logged-out user could still have an iPlanetDirectoryPro cookie but AM wouldn’t know they had logged out. Therefore, AM supports a feature that takes additional action when users log out of client-side sessions. AM can maintain a list of logged out client-side sessions in a session denylist in the CTS token store. Whenever users attempt to access AM with client-side sessions, AM checks the session denylist to validate that the user has not, in fact, logged out.

Because AM doesn’t modify client-side session cookies after they’re stored in the end user’s browser, and client-side sessions contain the session maximum time-to-live, you must protect them against tampering. Learn more in Client-side session security.

Authenticated sessions require the user or client to be able to hold on to cookies. Cookies provided by AM’s Session Service can contain a JSON Web Token (JWT) with the session or just a reference to where the session is stored.

AM issues a cookie to the user or entity regardless of the session location for client-side and server-side sessions. By default, the cookie’s name is iPlanetDirectoryPro. For authenticated sessions stored in the CTS token store, the cookie contains a reference to the session in the CTS token store and several other pieces of information. For authenticated sessions stored on the client, the iPlanetDirectoryPro cookie contains all the information that would be held in the CTS token store.

Client-side session cookies consist of two parts: The first part of the cookie is identical to the cookie used by server-side sessions, which ensures the compatibility of the cookies regardless of the session location. The second part is a JSON Web Token (JWT), which contains session information, as illustrated below:

Note that the examples are not to scale. The size of the client-side session cookie increases when you customize AM to store additional attributes in users' sessions. You’re responsible for ensuring the size of the cookie doesn’t exceed the maximum cookie size allowed by your end users' browsers.

Since the session cookie is either a pointer to the authenticated session or the actual session itself, you must configure AM to secure the session cookie against hijacking, session tampering, and other security concerns.

For example, terminating a session effectively logs the user or entity out of all realms, but the way AM terminates sessions has security implications depending on where AM stores the sessions. You can also configure the session time-to-live, idle timeout, the number of concurrent sessions for a user, and others.

Related information:

The AM admin UI lets the administrator view and manage active server-side authenticated sessions by realm by going to Realms > Realm Name > Sessions.

To search for active sessions, enter a username in the search box. AM retrieves the sessions for the user and displays them within a table. If no active server-side session is found, AM displays a session not found message.

You can end any sessions—except the current amAdmin user’s session—by selecting it and clicking the Invalidate Selected button. As a result, the user has to authenticate again.

To manage authenticated sessions using REST, send requests to the /json/sessions endpoint, as shown in the following examples.

Authenticated sessions can be upgraded to provide access to sensitive resources.

Consider a website for a university. Some resources, such as courses and degree catalogs, are free for anyone to access and don’t need to be protected. The university also provides the students with a portal they can use to access their grades. This portal is protected with a policy that requires users to authenticate. To pay tuition, students are required to present additional credentials to increase their authentication level and gain access to these functions.

Allowing authenticated users to provide additional credentials to access sensitive resources is called session upgrade. Session upgrade is AM’s mechanism to perform step-up authentication.