Sharing Sessions

In most production environments it is expected that the IBM Application Gateway (IAG) service will be replicated for load balancing and high availability purposes, and there will also be multiple instances of IAG protecting different applications. When a user is switched from one IAG instance to another it is important to make this a seamless experience for the user, without requiring them to provide their authentication information again.

The IAG can be configured to use a Redis service to share session information between multiple IAG instances, reducing the need for subsequent authentication operations when switching from one IAG instance to another.


Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache and message broker.

It is an independent and external service which can act as a centralized session repository for an IAG environment. Services in the environment can use the Redis server to provide failover for user sessions.

The Redis session cache provides the following benefits:

  • Manages sessions across multiple IAG instances;
  • Resolves session inactivity and session lifetime timeout consistency issues in a replicated environment;
  • Provides secure failover and single sign-on among different IAG instances;
  • Provides controls over the maximum number of allowed concurrent sessions per user;
  • Provides single sign-on capabilities and single sign-off among other websites in the same DNS domain;
  • Provides performance and high availability protection to the server environment in the event of hardware or software failure;
  • Allows administrators to view and modify remote IAG sessions using standard Redis tools.

Redis Failover

High availability in Redis is achieved through master-slave replication.

A master Redis server can have multiple Redis servers as slaves, preferably deployed on different nodes across multiple data centres. When the master is unavailable, one of the slaves can be promoted to become the new master and continue to serve data with little or no interruption.

Given the simplicity of Redis, there are many standard high-availability tools available that can monitor and manage a master-slave replica configuration. However, the most common HA solution that comes bundled with Redis is Redis Sentinels. Redis Sentinels run as a set of separate processes that in combination monitor Redis master-slave sets and provide automatic failover and reconfiguration.

In more recent times Redis introduced support for Redis Clusters. A Redis Cluster provides a way to run a Redis installation where data is automatically sharded across multiple Redis nodes. The IAG remote Redis session cache does not currently provide support for Redis Clusters.

Redis Collections

The IAG remote Redis session cache has the concept of 'collections' of replicated Redis servers to help with client-side partitioning of sessions.

Selection of the 'collection' which is to be used for a new session is based on the Host header found in the request – or a 'default' collection if no specific collection has been configured for the Host. This provides a sharding mechanism by which you can limit cross data centre traffic in a multi data centre environment.

When a session is created it will be created against the selected collection of Redis instances. The identifier for the collection will be included in the session cookie. If the client then switches to a different IAG server, the identifier from the session cookie will be used to determine the correct collection of Redis instances to use.

This concept is further illustrated in the following diagram:


Redis Keys

When a session is sent to the Redis server by IAG up to 3 keys will be created in the Redis server to represent the session.

To help isolate the IAG session data from any other data which might be stored in the Redis server each of the keys will be prefixed with a fixed string, as specified by the 'key_prefix' YAML entry within the Redis YAML object.

The following keys will be created by IAG:

  1. The session data itself will be stored in a single Redis 'hash'. The key for the session data will be constructed from the configured Redis key prefix, the 'session-' string, and the session identifier. For example: 'iag-session-hroagteRa2VRpzaqsFNFovI29d…';
  2. The list of IAG clients which have a local copy of the session will be stored in a Redis 'set'. The key for this set will be constructed from the configured Redis key prefix, the 'client-' string, and the name of the key which stores the corresponding session data. For example: 'iag-client-iag-session-hroagteRa2VRpzaqsFNFovI29d…'. This data is used to keep track of session inactivity across the multiple IAG servers;
  3. The count of concurrent sessions for a single user will be stored in a Redis 'set'. The key for this set will be constructed from the configured Redis key prefix, the 'user-' string, and the session identifier. For example: 'iag-user-hroagteRa2VRpzaqsFNFovI29d…'

The following figure is an example of the Redis keys which are created for a single user session:

    entry: value


In a Redis session cache environment, the client browser sends requests to the IAG service, which then interacts with the Redis server for session management.

The following diagram shows the basic process flow for session management in an environment where IAG is configured to use a remote Redis session cache:

  1. A user makes a request for a protected object located in the Web space protected by IAG A. IAG A intercepts the request and creates a local cache entry for the user. IAG A starts the authentication flow;
  2. The user authenticates against the configured identity provider and then provides authentication data to IAG A. IAG A updates the local session cache entry with the client's credential. Maintaining a local session cache improves the performance of that specific IAG server during future requests for resources.
  3. IAG A notifies the Redis server of the new session and the associated credential information. The Redis server maintains this information in its own database.
  4. IAG A sends a session cookie to the user's browser.
  5. An additional request for a resource by the same user, using the same session cookie, fails over to another server (IAG B).
  6. Using the session cookie IAG determines the name of the collection of Redis servers which should be used and then consults the Redis server to determine whether the user has a session available. The Redis server replies with the user's cached credential.
    IAG B uses the credential to trust the user and allows the request for the resource to proceed. The user is not prompted to login again.

Sharing sessions across multiple DNS domains

When operating in a multi-domain environment, you must use a different mechanism to communicate the session identifier to the IAG servers in the different DNS domains.

The index into the remote Redis session cache is stored and transmitted in a domain cookie. Clients do not present this cookie to servers that reside outside of the source DNS domain.

The 'master_authn_server_url' YAML entry, within the cross_domain_support YAML object, can be used to define a master authentication server which is responsible for establishing sessions and communicating the session identifier to other servers.

The flow which is used to establish a new session is illustrated in the following diagram:


When a request without an existing session is received the client will be redirected to the configured master authentication server. If a session does not already exist at the master authentication server a new authenticated session will be established. The master authentication server will then create a short-lived session code which is transmitted back to the originating server, which in turn can use this session code to obtain the real session identifier. The lifetime of the session code can be specified using the 'master_session_code_lifetime' YAML entry within the cross_domain_support YAML object.

Advantages of using the Redis session cache

The Redis session cache solution has many advantages over the JWE failover cookies solution for maintaining session state, as outlined in the following table.

TopicJWE Failover cookiesRedis session cache
SecuritySlightly less secure than the Redis session cache as identity information is stored in an encrypted cookie.Provides defense in depth with the Redis session cache located behind the DMZ.
Failover between IAG instancesHigher CPU usage is required for IAG to decrypt the failover cookie. A new session is established, which means that you do not share session semantics such as timeout information with other IAG instances.The Redis session cache shares sessions rather than using a single sign-on mechanism. Session semantics such as timeout information are shared between the various IAG instances.
Session policyNo concurrent session policy enforcement. No central administration of sessions.Concurrent session policy enforcement. Central management of sessions, including session termination using the Redis CLI tool.
MaintenanceRequires periodic renewal of failover cookie keys in line with corporate policy. This process is manual.The Redis session cache does not require encryption keys.
CookiesThe failover cookie is larger than the Redis session cache session cookie. The failover cookie can be configured to include many attributes, which can significantly increase its size.The Redis session cache uses a basic session cookie, which is relatively small. The cookies in a Redis session cache environment are typically less than 100 bytes.
LogoutIn browser scenarios, you cannot successfully log out with failover cookies turned on.You can logout from the browser session when you use the Redis session cache.

Restrictions when using the Redis session cache

There are a number of restrictions which apply when you are running an IAG environment that utilizes a remote Redis session cache.

  1. When an IAG instance is restarted the inactivity timeout for any sessions which that instance is referencing is reset. In this situation the inactivity timeout will be started again when the session is next referenced by an IAG instance. Alternatively, the lifetime timeout will ensure that the session still expires after a period of time;
  2. IAG does not provide an administrative interface to manage sessions which are stored in the Redis server. Native Redis utilities, like the redis-cli, should instead be used to manage the session data stored in the Redis server;
  3. Support for Redis Clusters is not available;
  4. IBM does not supply or support the Redis Server itself. The server must be obtained and managed separately. The IAG implementation requires a Redis server running at v6.0 or later.


The Redis session cache is enabled, and configured, using the redis YAML object. At a high level:

YAML ObjectDescription
redisThis is the top level configuration object which contains the configuration data which contains all of the configuration information for the Redis session cache.
concurrent_sessionsThis object contains the configuration information for restricting the number of concurrent user sessions.
collectionsThis object contains the configuration entries which are common to all replicated Redis servers within a single collection of servers. This includes configuration data such as: the Host header which is used to match this collection; the list of Redis server names within the collection; various performance and timeout configuration entries.
serversThis object contains the configuration entries which are used to define the connection details for a single Redis server. This includes configuration data such as: the server and port on which to connect to the Redis server; the password which is used when authenticating to the Redis server; SSL/TLS information for making a secure connection to the Redis server.

An example configuration is provided in the YAML reference: session