PingFederate Server

Directed clustering

This topic provides an overview of manual configuration of PingFederate sever nodes through directed clustering.

Directed clustering allows administrators to manually specify which PingFederate nodes should participate in tracking user sessions. Most group Remote Procedure Call (RPC)-based service implementations make use of a preferred-nodes concept, which assigns each node a list of other nodes, identified by index, with which it shares session-state information.

Each service implementation is controlled separately by a configuration file located in the <pf_install>/pingfederate/server/default/conf directory. You must replicate any changes manually for each cluster node.

The following tables indicate the configuration file that applies to each implementation and the applicable properties.

The Artifact-Message Persistence and Retrieval Service uses only the rpc.timeout setting.

Configuration file and service implementation
Configuration file RPC-based service implementation

cluster-account-locking.conf

cluster-artifact.conf

cluster-assertion-replay-prevention.conf

cluster-idp-session-registry.conf

cluster-inter-request-state.conf

cluster-session-revocation.conf

cluster-sp-session-registry.conf

Property description
Property Description

preferred.node.indices

A comma-separated list of indices identifying the nodes with which this node shares session-state information for the associated service. If left blank, this node sends session-state information to all nodes in the cluster as it processes SSO and logout requests.

The Artifact-Message Persistence and Retrieval Service and the Back-Channel Session Revocation Service do not support this parameter.

Ignored when adaptive clustering is enabled.

This property has no default value.

preferred.node.group.id

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

An alphanumeric group ID for a subcluster. If specified, each subcluster must have a unique group ID. At startup, PingFederate validates that the group ID is not already registered in the cluster by another list of preferred nodes. If the validation fails, PingFederate aborts the startup process and exits.

When the group ID is specified, the session identifier contains the information about the originating subcluster. This is helpful in deployments where PingFederate has been configured to manage authentication sessions on the Authentication → Policies → Sessions window. When an engine node receives a request to query and extend a session, it can route the request to the corresponding subcluster based on the session identifier value.

If subclusters are configured without specifying group IDs, a request to query and extend a session is processed on the subcluster that received the revocation status request, which may be different from the subcluster where the session is being tracked. As a result, the session could reach the idle timeout sooner than expected.

Ignored when adaptive clustering is enabled.

This property has no default value.

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 recipients to respond. When set to false, it waits for all recipients to respond.

The default value is true.

bulk.revoked.sris.timeout

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

Determines the amount of time (in milliseconds) PingFederate waits before aborting the download of revocation lists and reporting a timeout error. The default value is 10000, or 10 seconds.

A node downloads a full revocation list from another node during startup or when it rejoins a cluster after being disconnected from it.

read.local.only

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

Determines how PingFederate processes queries for revocation status.

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

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 for more information.

The default value is true.

Preferred node indices

Configuring the preferred.node.indices property can reduce the network communications and memory footprint. However, transaction volume and distribution can affect the resulting configuration. For more information on performance tuning, see PingFederate Performance Tuning Guide.

Individual services within a single cluster deployment can use different preferred nodes, meaning you can set different values for the preferred.node.indices property for each service.

Using preferred nodes can translate into a variety of deployment configurations. The following sections discuss three primary strategies to consider for meeting your network requirements:

It is possible to configure overrides for authentication-adapter processing based on the runtime node servicing a request. See Configuring the Cluster Node Authentication Selector for more information.