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.
Operational considerations
When configuring or troubleshooting runtime state management:
-
Identify the stateful item involved. Don’t treat all session data as one category.
-
Determine whether the item is node-local, held in PingFederate memory, shared through group RPC, or persisted externally.
-
Review the applicable setting in the
cluster-adaptive.conffile. -
For persistent sessions, verify that all participating node groups use the same external persistent-session store.
-
Account for asynchronous delivery between node groups and the possibility that the latest in-memory state has not reached the remote node group.
-
Review
size-limits.confbefore changing in-memory limits. Learn more in Configuring size limits.
|
The strategies described in this page apply to adaptive clustering. For directed clustering, learn how each service is managed in the individual service topics. |
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 |
Represents a user’s authentication session for an identity provider (IdP) 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) databases, supported Lightweight Directory Access Protocol (LDAP) stores, and DynamoDB. |
OAuth authorization code |
PingFederate node where the code was issued |
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 |
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 |
No |
In-memory implementations: controlled by the |
Single sign-on (SSO) 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 |
No |
Included with session-related replication in in-memory implementations through the |
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 |
Single logout (SLO) 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 |
Supports SLO for partners and adapters. |
Assertion Replay Prevention Service |
Group RPC |
No |
Controlled in in-memory implementations through the |
Tracks information used to detect assertion replay. |
Artifact-Message Persistence and Retrieval Service |
PingFederate node where the artifact was issued |
No |
Node-local, short-lived, and routed internally |
Supports the Agentless Integration Kit, Security Assertion Markup Language (SAML) 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) 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. |
Account Locking Service |
Group RPC |
No |
Controlled in in-memory implementations through the |
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. |
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. 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 <pf_install>/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.
| Setting | State or behavior | Operational significance |
|---|---|---|
|
All runtime state |
The number of nodes within a node group to which each state record is replicated. The default is 3. |
|
All runtime state |
Determines whether this node stores runtime state. By default, all nodes store state. |
|
Session-related state, including authentication sessions, IdP and SP session-registry data, IRSM adapter attributes, and SLO-related data |
Default is |
|
IRSM transaction state |
Default is |
|
Reference-style OAuth bearer tokens |
Default is |
|
Reference-token replication timing |
Default is |
|
Assertion replay state |
Default is |
|
Account-locking state |
Default is |
Learn more about multi-region deployments in Multi-region support.
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.
For example, in a deployment with two AWS regions and one node group per region:
-
A user authenticates in region A and receives a session cookie.
-
Region A becomes unavailable, and load balancing sends the user to region B.
-
Region B receives the cookie but doesn’t have the authentication session in memory.
-
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.
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.
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.
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.