PingFederate Server

Configuring cluster encryption and authentication

When you use the obfuscate or clusterkey utility to set pf.cluster.auth.pwd, the resulting value is encrypted with key material from the console node’s pf.jwk file. Each engine node must contain the relevant key material to deobfuscate the password and join the cluster. If you use either utility, start with Configure the cluster authentication password, then complete the matching procedure.

Complete the procedure that matches your situation: enabling cluster encryption on an existing cluster, adding a new engine node, or converting an existing PingFederate instance to an engine node.

Before you begin

  • Identify the console node and all engine nodes in the cluster.

  • If you are enabling cluster encryption on an existing cluster, plan a maintenance window because you must stop and restart all cluster nodes.

  • If you use a MasterKeyEncryptor, use the Add a new engine node procedure. Manual key merging is not possible with a MasterKeyEncryptor.

Configure the cluster authentication password

  1. On the console node, use one of the following utilities in the <pf_install>/pingfederate/bin directory to generate or obfuscate the cluster authentication password:

    • Use the obfuscate utility (obfuscate.bat for Windows and obfuscate.sh for Linux) to obfuscate a password.

    • Use the clusterkey utility (clusterkey.bat for Windows and clusterkey.sh for Linux) to generate an obfuscated cluster password.

  2. Copy the generated value to pf.cluster.auth.pwd in <pf_install>/pingfederate/bin/run.properties on the console node.

    Use the same value on every node. Don’t generate a separate value on each engine node.

Enable encryption on an existing cluster

  1. Replicate the console node’s configuration to all engine nodes. This makes the required key material from the console node’s pf.jwk file available on the engine nodes.

  2. Stop all cluster nodes.

  3. Set the same, non-blank pf.cluster.auth.pwd value in <pf_install>/pingfederate/bin/run.properties on every node.

    Configuration replication does not copy the run.properties file. Set this property manually on each node.

  4. Set pf.cluster.encrypt to true in run.properties on the console node and every engine node.

  5. Start all cluster nodes.

Add a new engine node

  1. Extract the PingFederate package on the engine node.

  2. Before starting the engine node for the first time, copy <pf_install>/pingfederate/server/default/data/pf.jwk from the console node to the same path on the engine node.

  3. If you use a MasterKeyEncryptor, also copy <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.crypto.jwk.MasterKeySet.xml from the console node to the engine node.

  4. Complete the engine setup.

  5. Set the same pf.cluster.auth.pwd and pf.cluster.encrypt values as the other nodes, and start the engine node.

Convert an existing PingFederate instance to an engine node

Don’t use this procedure if you use a MasterKeyEncryptor. Instead, start with a fresh engine node and follow Add a new engine node.

  1. Stop the PingFederate instance.

  2. Manually merge the keys from the console node’s <pf_install>/pingfederate/server/default/data/pf.jwk file into the instance’s corresponding pf.jwk file. Don’t replace the instance’s existing key material.

  3. Set the same pf.cluster.auth.pwd and pf.cluster.encrypt values as the other nodes.

  4. Start the engine node.

Result

All nodes use the same cluster authentication password. If you used an obfuscated or utility-generated value, each engine node contains the key material required to deobfuscate the password and join the cluster. When pf.cluster.encrypt is set to true, communication between cluster nodes is encrypted.

After completing the procedure, return to Deploying cluster servers and continue with Sign on to the admin console.