Storing session state in an external Redis session repository

This article describes how to store Airlock IAM session state in a Redis session repository.

Airlock IAM relies on session state stored server-side. Most requests processed by Airlock IAM must be able to access the up-to-date session state. If multiple IAM instances are active, how session information is stored and that it can be shared among the IAM instances is relevant.

As of IAM 8.2, the feature is available for the Loginapp, Adminapp, and Transaction Approval modules.

What is Redis?

Redis is a fast and proven open-source data storage solution that can be used as a distributed cache.

  • There are two places to store session state:
  • In the local memory of the IAM instance. This is the default.
  • In an external Redis session repository. How to set this up is described in this article.

Why store session information in Redis?

Storing session state in an external session repository has many advantages and is especially useful in active-active setups, mostly in cloud environments such as Kubernetes. The challenge in such environments is typically maintaining a session state for short-lived containers and non-session-sticky load balancing.

  • Advantages of storing session state in Redis:
  • Load balancing does not need to be session-sticky.
  • Allows horizontal scaling.
  • Better support cloud-native environments (short-lived IAM containers).
  • No session loss in failover situations.
  • Basis for future upgrades at runtime (rolling updates).
  • Disadvantages of storing session state in Redis:
  • Requires Redis session repository (not part of Airlock IAM).
  • Small negative impact on performance (due to communication with Redis).

How to use the feature?

Storing session state in Redis is thought for production environments with a separately managed IAM configuration. The Config Editor does not work in active-active setups and it is therefore not possible to configure a cluster of active IAM instances using the Config Editor running in these instances.

  1. Instead, do the following:
  2. Manage the configuration for the IAM cluster in a separate IAM instance (e.g. single-instance IAM setup for configuration).
  3. Store the resulting IAM configuration XML file.
  4. Make the configuration available to the IAM instances that are part of the cluster.

We recommend using Configuration variables or Configuration environments to manage configuration for different stages.

  • If using a shared instance folder for multiple active instances, consider the following:
  • Most files in the instance directory are read-only, but not all.
  • Ensure that multiple active IAM instances do not overwrite files from each other. This is especially true for:
    • .activated-configs (each IAM instance writes the configuration it activates)
    • log files
    • generated reports (e.g. password letters)
  • Where possible, adapt the configuration so files written by IAM instances are placed outside the shared instance folder.

Note that not all IAM features and modules support this feature. Check the limitations section below for further details.


  1. To enable the feature, proceed as follows:
  2. Go to:
  3. If not using MAIN SETTINGS, the feature can be directly configured in the affected IAM modules (e.g. Loginapp, Adminapp).

  4. In property State Repository, add and edit the Redis State Repository plugin.
  5. Configure the connection to Redis (Redis URI, Username, Password). You may use the Testlet (the yellow flash) to test the connection.
  6. Configure Encryption
    • Choose AES 128 GCM State Encryption to encrypt state before being sent to Redis. All instances sharing state must use the same encryption key. If the encryption key is lost, the state cannot be recovered.
    • Choose Migrating State Encryption to migrate from no encryption to encryption (or from encryption to a different type of encryption). Read the plugin documentation for further details.
    • This option is useful if migration from IAM 8.1 and you already stored state in Redis with 8.1, since IAM 8.1 did not yet support state encryption.

      To prevent losing session state during the migration from unencrypted to encrypted session state use the plugin Migrating State Encryption and configure its property Previous Encryption as No State Encryption and New Encryption as AES 128 GCM State Encryption. The Migrating State Encryption can be replaced by the contained AES 128 GCM State Encryption after the completion of the migration. The migration duration corresponds to the maximum IAM session lifetime.

    • Choose No State Encryption to store state unencrypted.
  7. Configure TLS Settings and Performance Tuning properties as required.

Important security advisory

Since session information includes sensitive information, it is essential that the connection to Redis is protected and only legitimate service accounts have access to the data in Redis.

It is recommended to encrypt state information in Redis.

  • Configure Redis and the Redis State Repository plugin such that:
  • Data in transit between IAM and Redis is encrypted using sensible TLS settings.
  • Ensure IAM can verify that it connects to the correct Redis endpoint (verify server hostname with meaningful server certificate).
  • Ensure that legitimate systems and administrators know the username and password used to access Redis.
  • To further secure the connection, consider using client certificates.
  • Other configuration options to consider when using the Redis State Repository:
  • If using many active IAM instances in parallel:
    • Note that connection pools 3rd-party systems (e.g. DB connections) are created per instance. This may result in more connections than the 3rd-party system can handle.
    • Consider reconfiguring the connection pools depending on the number of IAM instances.
  • If accepting SSO tickets in authentication flows or using User representation:
    • It is highly recommended to store accepted SSO tickets in the IAM database (instead of the memory).
    • Note that Accepted SSO tickets stored in memory are not stored in the Redis session repository.
  • Review the session timeout settings in the Loginapp and Adminapp modules (Session Idle Timeout and Session Lifetime in the Advanced Settings property group).

Supported IAM features and limitations

Storing session states in Redis is not supported for all IAM features. The following tables show what features can be used with Redis and what is planned to be supported in future IAM releases.

IAM Module

Support state

Since release


Supported (see limitations below)



Supported (see limitations below)


Transaction Approval

Not yet supported


Service Container

Not supported

Not planned

API Policy Service

Not supported

Not planned

The Adminapp is supported with the following exceptions:

Adminapp Feature

Support state

Since release

Config Editor

Not supported.

Not planned

Bulk changes (in user management).

Not supported.

Not planned

All other features