PingFederate Server

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:

  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 and Storing PingFederate data with Redis.

  • 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.

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.

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. 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) 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) 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, 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, 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. 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. 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.

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:

  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.

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.