In essence, each session receives an address from within an internally-defined range. For redundancy, multiple nodes store each session. These nodes form a replica set. Any node that receives a request and must look up or store session-state information can do so by calculating the address of the session and reaching out to the corresponding replica set.

As individual nodes join and leave the cluster, adaptive clustering redistributes session-state information to maintain the replica set throughout the cluster.

The default size of a replica set is three, which provides redundancy in case two nodes fail and ensures that a single node's slow response time doesn't delay requests. The replication.factor setting is in the <pf_install>/pingfederate/server/default/conf/cluster-adaptive.conf file.

Enable adaptive clustering by setting the pf.cluster.adaptive property in the run.properties file to true. This is the default state in new installations. For upgrades, if such property is not found or is set to false, the system disables adaptive clustering and enables directed clustering instead. To enable or disable adaptive clustering, set the pf.cluster.adaptive property to true or false on each node and then restart PingFederate. The run.properties file is in the <pf_install>/pingfederate/bin directory.

Important:

After making changes to the cluster-adaptive.conf and the run.properties files, you must manually repeat the changes to all nodes in the cluster. The configuration replication process does not push these files across the cluster. When you are finished, restart PingFederate to apply the changes.

Note:

Adaptive clustering does not support the SAML 2.0 single logout (SLO) profile using the SOAP binding. If you have configured one or more SAML 2.0 connections to support SLO using SOAP, you must either share all nodes or designate state servers deployment strategies in directed clustering. For more information, see Directed clustering.

Other advanced settings

Fine-tune each runtime state-management service implementation separately by modifying a configuration file located in the <pf_install>/pingfederate/server/default/conf directory. After making changes in these files, you must apply the changes to all nodes in the cluster manually.

Note:

The adaptive clustering concept is not applicable to the Artifact-Message Persistence and Retrieval Service, which always shares messages across all nodes to fulfill its objectives. As needed, you can modify other applicable properties, such as the rpc.timeout property. For more information, see Artifact-Message Persistence and Retrieval Service.

The following tables indicate the configuration file that applies to each implementation and the applicable properties. See the indicated sections for detailed information about each implementation.

Configuration file and service implementation
Configuration file RPC-based service implementation
cluster-account-locking.conf Account Locking Service
cluster-artifact.conf Artifact-Message Persistence and Retrieval Service
cluster-assertion-replay-prevention.conf Assertion Replay Prevention Service
cluster-idp-session-registry.conf IdP Session Registry Service
cluster-inter-request-state.conf Inter-Request State-Management (IRSM) Service
cluster-session-revocation.conf Back-Channel Session Revocation Service
cluster-sp-session-registry.conf SP Session Registry Service
Property description
Property Description
rpc.timeout How long, in milliseconds, this node waits before timing out unresponsive RPC invocations. The default value is 500, or half a second.
synchronous.retrieve.majority.only Indicates how many responses to wait for when making synchronous remote procedure calls. When set to true, this node waits for the majority of the local replica set to respond. When set to false, it waits for all recipients to respond. true is the default value.
Note: This property is not applicable to the Account Locking Service and not found in the cluster-account-locking.conf file.
bulk.revoked.sris.timeout

(found only in the cluster-session-revocation.conf file)

A node downloads a full revocation list from another node during startup or when it rejoins a cluster after being disconnected from it, for example due to a temporary network issue. This setting determines the amount of time in milliseconds PingFederate waits before aborting the download and reporting a timeout error.

The default value is 10000, which is 10 seconds.

read.local.only

(found only in the cluster-session-revocation.conf file)

Determines how PingFederate should process queries for revocation status.

When set to true, PingFederate processes queries for revocation status locally. When set to false, the processing node pulls revocation status from other engine nodes in the cluster, subject to the rpc.timeout value. true is the default value.

Note:

When adding a session to the revocation list, the processing node always propagates the information to all engine nodes in the cluster.For more information, see Back-Channel Session Revocation Service.

Note:

When you have enabled adaptive clustering, PingFederate ignores other properties found in these configuration files—namely preferred.node.indices and preferred.node.group.id. The latter is only in the cluster-idp-session-registry.conf file.