Adaptive clustering automatically distributes session-state information to multiple nodes. Administrators are not required to modify individual configuration files to specify which nodes should participate in tracking user sessions.

In essence, each session is assigned an address from in an internally defined range. Each node is aware of which nodes are responsible for which segments of (session) addresses such that the entire range is covered. For redundancy, each session is stored on multiple nodes; 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.

Adaptive clustering is also designed to handle changes in cluster membership with ease. As individual nodes join and leave the cluster, adaptive clustering redistributes session-state information so that the replica set is maintained throughout the cluster.

The default size of a replica set is three, which provides redundancy in case two nodes in the replica set fail and ensures that requests are not delayed when a single node is slow to respond. The setting (replication.factor) is stored in the cluster-adaptive.conf file, located in the <pf_install>/pingfederate/server/default/conf directory.

Adaptive clustering is enabled for new installations; the pf.cluster.adaptive property in the run.properties file is set to true. For upgrades, if such property is not found or is set to false, adaptive clustering is disabled and directed clustering is used 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 located in the <pf_install>/pingfederate/bin directory.

Important:

After making changes to the cluster-adaptive.conf and the run.properties files, you must apply the changes to all nodes in the cluster manually. The configuration replication process does not push these files across the cluster. Additionally, restart PingFederate if it is running.

Note:

Adaptive clustering does not support the SAML 2.0 single logout (SLO) profile using the SOAP binding. If one or more SAML 2.0 connections are configured to support SLO via SOAP, you must choose between the sharing all nodes and designating state servers deployment strategies in directed clustering (see Directed clustering).

Other advanced settings

As needed, you can 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. Its messages are always shared across all nodes to fulfill their objectives. As needed, you can modify other applicable properties, such as the rpc.timeout property.

The following tables indicate the configuration file that applies to each implementation and the applicable properties. Refer to 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, which is half a second.

synchronous.retrieve.majority.only Indicates how many responses to wait for when making synchronous remote procedure calls (values: true or false). 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.

Note this property is not applicable to the Account Locking Service and not found in the cluster-account-locking.conf file.

The default value is true.

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 (possibly 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 whether PingFederate should process queries for revocation status by searching the local revocation list or collecting the information from other engine nodes in the cluster.

When set to true, queries for revocation status are processed locally. When false, the processing node pulls revocation status from other engine nodes in the cluster (subject to the rpc.timeout value).

Note:

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

The default value is true.

Note:

Other properties found in these configuration files, namely the preferred.node.indices and preferred.node.group.id properties, are ignored when adaptive clustering is enabled. (The latter is found only in the cluster-idp-session-registry.conf file.)