--- title: Runtime state-management strategies description: Where PingFederate holds each type of runtime state, how it replicates between node groups, and how it recovers after failures. component: pingfederate version: 13.0 page_id: pingfederate:server_clustering_guide:pf_runtime_state_management_strategies canonical_url: https://docs.pingidentity.com/pingfederate/13.1/server_clustering_guide/pf_runtime_state_management_strategies.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: October 28, 2026 superseded_by: https://docs.pingidentity.com/pingfederate/13.1/server_clustering_guide/pf_runtime_state_management_strategies.html section_ids: operational-considerations: Operational considerations state-management-strategies: State-management strategies adaptive-cluster-replication: Adaptive-cluster replication failover-and-recovery: Failover and recovery session-registries-and-adapter-state: Session registries and adapter state node-local-and-short-lived-state: Node-local and short-lived state in-memory-limits-and-revocation-state: In-memory limits and revocation state --- # Runtime state-management strategies PingFederate manages several types of runtime state. Their behavior differs according to where the state is held, whether it's persistent, and how it's distributed within and between node groups. Learn more about the service implementations in [Runtime state-management services](pf_runtime_state_manage_serv.html). ## Operational considerations When configuring or troubleshooting runtime state management: 1. Identify the stateful item involved. Don't treat all session data as one category. 2. Determine whether the item is node-local, held in PingFederate memory, shared through group RPC, stored in Redis, or persisted externally. 3. Review the applicable setting in the `cluster-adaptive.conf` file. 4. For persistent sessions, verify that all participating node groups use the same external persistent-session store. 5. Account for asynchronous delivery between node groups and the possibility that the latest in-memory state has not reached the remote node group. 6. Review `size-limits.conf` and, where applicable, `redis-size-limits.conf` before changing in-memory limits. Learn more in [Configuring size limits](../administrators_reference_guide/pf_config_size_limits.html) and [Storing PingFederate data with Redis](../administrators_reference_guide/pf_storing_pf_data_redis.html). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * The strategies described in this page apply to adaptive clustering. For directed clustering, learn how each service is managed in the individual service topics. * Redis support is service-dependent. In-memory (Group RPC) state is lost on a full cluster restart unless the service is configured to store data in Redis or an external store. Learn more in [Storing PingFederate data with Redis](../administrators_reference_guide/pf_storing_pf_data_redis.html). | ## State-management strategies The following table describes PingFederate's state types and where they are managed: | Stateful item | Managed in | Persistable | Distribution and replication | Notes | | ------------------------------------------------------------ | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication session | PingFederate memory or an external persistent session store | Yes | Controlled by the `inter.group.replicate.sessions` setting. Refer to [Failover and recovery](#failover-and-recovery). | Represents a user's authentication session for an identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* adapter or IdP connection. It doesn't include profile, self-service password reset (SSPR), or Local Identity Profile (LIP) state. The default store is the internal HSQLDB database. External options are Java database connectivity (JDBC) *(tooltip: \
\

A Java API that allows Java programs to interact with databases.\

\
)* databases, supported Lightweight Directory Access Protocol (LDAP) *(tooltip: \
\

An open, cross platform protocol used for interacting with directory services.\

\
)* stores, and DynamoDB. Redis isn't an authentication-session storage option. | | OAuth authorization code | PingFederate node where the code was issued, or Redis | No | Node-local, short-lived, and routed internally | A code sent to the client to exchange for an access token. | | OAuth bearer token (reference style) | Group RPC | No | Controlled by the `inter.group.replicate.reference.tokens` setting, and replicated synchronously between node groups by default. | A non-persistent reference-style bearer token. Asynchronous replication can reduce token-creation time but can delay validation in another node group. | | Persistent grants | External data store | Yes | Not replicated between node groups, and retrieved from the external shared store as needed. Node-group replication settings don't apply to this state. | Used for implicit, authorization-code, and resource owner password credentials flows with a refresh token. | | Inter-Request State-Management (IRSM) state | Group RPC, or Redis | No | In-memory implementations: controlled by the `inter.group.replicate.transaction.state` setting, and asynchronous between node groups when enabled. | Single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* transaction state, such as the user's current node within the authentication policy. This state isn't restored from persistent authentication-session storage. | | IRSM attributes | Group RPC, or Redis | No | Included with session-related replication in in-memory implementations through the `inter.group.replicate.sessions` setting | Session attributes created and managed internally by adapters, such as HTML Form Adapter session tracking. | | IdP Session Registry | Group RPC | No | Included with session-related replication in in-memory implementations through the `inter.group.replicate.sessions` setting | Single logout (SLO) *(tooltip: \
\

The process of signing a user out of multiple sites where the user has started a SSO session.\

\
)* for partners and adapters. In Group RPC implementations, it also stores authentication sessions in memory. | | SP Session Registry | Group RPC | No | Included with session-related replication in in-memory implementations through the `inter.group.replicate.sessions` setting | Supports SLO for partners and adapters. | | Assertion Replay Prevention Service | Group RPC | No | Controlled in in-memory implementations through the `inter.group.replicate.assertion.replay` setting. | Tracks information used to detect assertion replay. | | Artifact-Message Persistence and Retrieval Service | PingFederate node where the artifact was issued, or Redis | No | Node-local, short-lived, and routed internally | Supports the [Agentless Integration Kit](https://docs.pingidentity.com/integrations/agentless/pf_agentless_ik.html), Security Assertion Markup Language (SAML) *(tooltip: \
\

A standard, XML-based, message-exchange framework enabling the secure transmittal of authentication tokens and other user attributes across domains.\

\
)* 2.0 artifact binding, and the OAuth authorization-code flow. Artifact data, including authorization codes, is one-time-use and short-lived. | | Session revocation (Back-Channel Session Revocation Service) | Memory on all engine nodes | No | In-memory: propagated to all engine nodes. | Includes revoked session identifiers and JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* access-token jti claims. JWT access-token revocation is controlled by the **Enable Token Revocation** option when configuring an access token management instance. A new node downloads the revocation list from other nodes during initialization or after a network partition. Learn more in [Configuring an access token management instance](../administrators_reference_guide/pf_configuring_access_token_management_instance.html). | | Account Locking Service | Group RPC, or Redis | No | Controlled in in-memory implementations through the `inter.group.replicate.account.locking` setting. Not controlled by cluster settings when stored in Redis. | Tracks failed authentication attempts for lockout enforcement. | | Account linking (SAML 2.0) | External data store | Yes | Not replicated between node groups, and retrieved from the external shared store as needed. Node-group replication settings don't apply to this state. | Supports LDAP stores, JDBC databases, and DynamoDB. | | OAuth clients | PingFederate XML file or external data store | Yes | Not replicated between node groups, and included in the configuration archive. | | | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In the **Persistable** column, Yes indicates that the state has a persistent-storage mechanism, such as a persistent data store or configuration file. State without such a mechanism exists only as runtime data in memory or a cache. State in the Redis cache is marked No. It can survive a full cluster restart, but it remains subject to the service's expiration and, where applicable, one-time-use semantics. | ## Adaptive-cluster replication Adaptive clustering distributes state within a node group and can replicate selected state asynchronously to other node groups. Learn more in [Adaptive clustering](pf_adaptiv_cluster.html). A node group might represent a region, but the replication scope is the configured node-group topology rather than "region" as a generic concept. Within a node group, PingFederate shares state synchronously with the number of nodes specified by the `replication.factor` setting. Most requests wait for responses from a majority of that replica set. Each node group maintains its own replica set. A state record is replicated to the configured number of nodes in the local node group and to the same number in each other node group. Between node groups, replication is asynchronous. The sending node doesn't receive delivery confirmation from the remote node group. Cross-node-group replication isn't a synchronous backup. The state can be lost if a node group fails before its state reaches another node group. The following table describes settings in the `/pingfederate/server/default/conf/cluster-adaptive.conf` file that control replication for specific state types. Unless otherwise noted, these settings apply to the Group RPC implementations. They don't control Redis implementations. | Setting | State or behavior | Operational significance | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `replication.factor` | All runtime state | The number of nodes within a node group to which each state record is replicated. The default is 3. | | `track.state` | All runtime state | Determines whether this node stores runtime state. By default, all nodes store state. | | `inter.group.replicate.sessions` | Session-related state, including authentication sessions, IdP and SP session-registry data, IRSM adapter attributes, and SLO-related data | Default is `true`. Replication between node groups is asynchronous. When disabled, session-related state isn't replicated between node groups. Persistent sessions can still be recovered from shared external storage. | | `inter.group.replicate.transaction.state` | IRSM transaction state | Default is `false`. When enabled, transaction state is replicated asynchronously between node groups. Transaction state isn't persistent, so a recovered node group doesn't receive this state from a surviving node group after it returns. | | `inter.group.replicate.reference.tokens` | Reference-style OAuth bearer tokens | Default is `true`. | | `inter.group.replicate.reference.tokens.synchronous` | Reference-token replication timing | Default is `true`. Synchronous replication ensures that reference tokens can be validated immediately on other node groups. Set to `false` to reduce token-creation time. | | `inter.group.replicate.assertion.replay` | Assertion replay state | Default is `true`. Replication between node groups is asynchronous. | | `inter.group.replicate.account.locking` | Account-locking state | Default is `true`. Replication between node groups is asynchronous. | Learn more about multi-region deployments in [Multi-region support](pf_multi_region_supp.html). ## Failover and recovery Persistent sessions provide a recovery path that is independent of in-memory replication when the affected node groups use the same external persistent-session store. Learn how to configure external storage for authentication sessions in [Defining a datastore for persistent authentication sessions](../administrators_reference_guide/pf_defining_datastore_persis_auth_sess.html). For example, in a deployment with two AWS regions and one node group per region: 1. A user authenticates in region A and receives a session cookie. 2. Region A becomes unavailable, and load balancing sends the user to region B. 3. Region B receives the cookie but doesn't have the authentication session in memory. 4. If persistent sessions are enabled and both node groups use the same external store, PingFederate queries that store, retrieves the session, and caches it in the active region. This recovery path works even when `inter.group.replicate.sessions` is set to `false`, because the session is retrieved from persistent storage rather than from the failed node group. The session cookie must still be valid, and the surviving region must be configured to use the same persistent-session store. When `inter.group.replicate.sessions` is set to `true`, the session can also be replicated asynchronously to the other region's node group. This replication can allow the surviving region to serve the session from memory. However, asynchronous delivery doesn't guarantee that the latest state has arrived before a failure. Persistent storage remains the recovery source for persistent sessions. When a failed node group returns, newly started engines don't automatically pull all session state from the node group that remained available. Persistent sessions can be retrieved from the shared external store when requested. Non-persistent Group RPC or in-memory state must be recreated by the applicable flow. State stored in Redis, such as IRSM data, remains available unless it has expired. Transaction state isn't persistent. If a node group fails while an SSO transaction is in progress, the transaction might not be recoverable after the node group restarts, even when persistent authentication sessions are configured. ## Session registries and adapter state Authentication sessions, session registries, and adapter attributes are related but distinct: * Authentication sessions represent a user's authentication session for an IdP adapter or IdP connection. They can be held in PingFederate memory or an external persistent session store. * IRSM attributes are session attributes created and managed internally by adapters, such as HTML Form Adapter session tracking. * IdP and SP session registries support SLO for partners and adapters. In Group RPC implementations, the IdP session registry also stores authentication sessions in memory. In Group RPC implementations, the `inter.group.replicate.sessions` setting controls replication for all of these services. They share a replication path but don't have identical persistence semantics. Authentication sessions can be persisted to an external store, while session-registry data and adapter attributes aren't stored in the persistent authentication-session store. ## Node-local and short-lived state In in-memory and Group RPC implementations, the following values are created on a specific PingFederate node and aren't persisted: * OAuth authorization codes * Artifact messages These values are short-lived and use internal routing where applicable. They aren't durable session state and aren't recoverable through persistent-session storage. Redis implementations store these values in Redis instead, where they survive a cluster restart but remain subject to the service's expiration and one-time-use semantics. ## In-memory limits and revocation state The `size-limits.conf` file contains limits for selected in-memory state. For example, the `SessionRevocationServiceMapImpl.max.revoked.sris` setting controls the maximum number of revoked session identifiers kept in memory, including revoked JWT access-token jti claims. Learn more in [Configuring size limits](../administrators_reference_guide/pf_config_size_limits.html). In the in-memory implementation, revocation state is propagated to all engine nodes. A newly started node downloads the full list of revoked identifiers from other nodes during initialization or after a network partition. The revocation list therefore survives the restart of an individual node. If the entire cluster restarts, no node can provide the list and the in-memory revocation state is lost. The `redis-size-limits.conf` file covers IRSM expiry and attribute limits for Redis deployments. Learn more in [Storing PingFederate data with Redis](../administrators_reference_guide/pf_storing_pf_data_redis.html).