PingFederate Server

Managing configuration encryption keys

PingFederate maintains a set of configuration encryption keys to encrypt and decrypt sensitive information.

These keys encrypt and decrypt sensitive configuration information and runtime data like the following:

  • Datastore passwords

  • Adapter shared secrets

  • Reversible secrets in OAuth clients

  • Data encrypted using the obfuscate.sh/bat script, such as the cluster authentication password in the run.properties file

  • User attributes in access grants and persistent sessions

PingFederate stores configuration encryption keys in the pf.jwk file in chronological order, starting with the newest key at the top. The pf.jwk file is in the <pf_install>/pingfederate/server/default/data directory.

{"keys":[
{"kty":"oct","kid":"WTIsxFH5gE","k":"FKDByJ13ZHPpi_oLI2_4q_lFgKNi7J1fx8HTyTJINPc","creationDate":1639163017},
{"kty":"oct","kid":"W31mrSXqnH","k":"Keadc5M4cFoLKdWtR2zaEx8P0Dzs-L2U35JNGgLzDHI","creationDate":1639162773}
]}

For encryption, PingFederate uses the newest, or primary, key in pf.jwk. For decryption, PingFederate tries each key in the file, starting with the primary key, until it succeeds or until there are no more keys to try.

Managing configuration encryption keys involves regularly rotating the keys and re-encrypting sensitive information with new keys. When pf.jwk accumulates keys that are no longer needed for decryption, you can delete them. Use the PingFederate administrative console and the configkeymgr utility to manage your configuration encryption keys.

The administrative console lets you rotate the keys. The configkeymgr utility lets you perform the following tasks:

  • List all of the configuration encryption keys.

  • Rotate the keys, creating a new key and setting it as the primary encryption key.

  • Re-encrypt encrypted configuration data using the primary encryption key.

  • Delete unused configuration encryption keys.

The utility, located in the <pf_install>/pingfederate/bin directory, comes in two variants:

  • configkeymgr.bat for Windows

  • configkeymgr.sh for Linux

When managing configuration encryption keys, PingFederate logs events in the configkeymgr.log, admin.log, or admin-api.log, depending on what you used to perform the tasks.

You should protect your configuration encryption keys with AWS KMS or a custom solution based on the PingFederate SDK (the MasterKeyEncryptor interface).

Rotating configuration encryption keys

You can use the PingFederate administrative console to rotate configuration encryption keys.

About this task

To maintain security, you should regularly rotate the configuration encryption keys. Rotating keys involves generating a new key and making it the new primary key. PingFederate will use the new primary key to encrypt sensitive information.

To rotate configuration encryption keys:

Steps

  1. In the administrative console, go to Security → Certificate & Key Management → Configuration Encryption Keys.

  2. Click Rotate.

    Result:

    PingFederate generates a new key, inserts it into the top of the pf.jwk file, and displays it at the top of the Configuration Encryption Keys window.

Next steps

After you rotate the configuration encryption keys, you should use the configkeymgr utility to re-encrypt information that was encrypted with previous keys.

Re-encrypting sensitive information with configuration encryption keys

You can use the configkeymgr command-line utility to re-encrypt sensitive configuration information and OAuth client secrets.

About this task

You should re-encrypt sensitive information after you rotate the configuration encryption keys.

To re-encrypt sensitive configuration information:

Steps

  1. Stop the PingFederate console node.

  2. Run the configkeymgr utility on the console node:

    • If PingFederate is running on Windows, open a command prompt, go to <pf_install>/pingfederate/bin, and run configkeymgr.bat.

    • If PingFederate is running on Linux, open a terminal window, go to <pf_install>/pingfederate/bin, and run configkeymgr.sh.

      Result:

    The utility displays its usage help.

  3. Run the reencrypt command.

    The utility offers optional arguments for the reencrypt command.

    Example:

    For example, to perform a dry run of the reencrypt command in a Linux environment, enter the following command.

    ./configkeymgr.sh --reencrypt --dry-run

  4. Restart the PingFederate console node.

  5. If PingFederate is running in a cluster:

    1. Replicate the configuration to the engine nodes.

    2. Run the configkeymgr utility on the engine nodes to re-encrypt data that is not included in the replication archive, such as sensitive data defined in the run.properties file.

      You can run the utility on engine nodes without stopping them.

Deleting unused configuration encryption keys

When PingFederate accumulates configuration encryption keys that are no longer needed for decryption, you can delete them.

About this task

Unused keys accumulate in the pf.jwk file as keys are rotated. They also accumulate when data archives are imported. The configkeymgr utility lets you delete unused keys.

The utility lets you delete a specific unused key, all unused keys that were created before a specific time, or all unused keys that were created before a specific key was created. If you use the --before-timestamp <arg> parameter, where <arg> is a timestamp argument, specify the timestamp value in one of the following formats:

  • The format on the Configuration Encryption Keys window, which looks like "Tue Dec 14 14:50:20 PST 2021"

  • The format in the administrative API, which looks like 2021-12-14T22:50:20.000Z

  • The Unix timestamp format from the pf.jwk file, which looks like 1639522220

For more information about the delete command’s parameters, see the utility’s usage help.

When you run the delete command, the utility first scans the configuration data, looking for in-use keys. If the utility finds any in-use keys within the scope defined by the command’s parameters, it will not delete any keys.

The scan to determine if the keys are in use only works for keys used in PingFederate’s configuration or in OAuth clients. The utility does not perform the in-use check on sessions and grants. If you delete in-use keys that are referenced by unexpired sessions or grants, users will need to re-authenticate or re-authorize.

Before you delete configuration encryption keys, you should wait until the sessions and grants that reference older keys expire. To do that, first determine when the configuration data was last re-encrypted with a new key. Next, find the lifetime of the sessions and grants. Then wait the lifetime of the sessions or grants, whichever is longer, after the re-encryption date. For example, if you re-encrypted the data on June 1st, sessions last 8 hours, and grants last 30 days, then wait at least 30 days after June 1st before you delete the encryption keys.

To delete unused configuration encryption keys:

Steps

  1. Stop the PingFederate console node.

  2. Run the configkeymgr utility on the console node:

    • If PingFederate is running on Windows, open a command prompt, go to <pf_install>/pingfederate/bin, and run configkeymgr.bat.

    • If PingFederate is running on Linux, open a terminal window, go to <pf_install>/pingfederate/bin, and run configkeymgr.sh.

      Result:

    The utility displays its usage help.

  3. Run the delete command with one of the following scope parameters:

    • --before-timestamp <arg> deletes any keys that were created before the specified time.

    • --keyid <arg> deletes the key with the specified key ID.

    • --before-keyid <arg> deletes any keys that were created before the specified key.

      Example:

      For example, in a Linux environment, run the following command to delete unused keys that were created before a specific time.

      ./configkeymgr.sh --delete --before-timestamp "Tue Jun 15 14:00:00 PST 2021"

  4. Restart the PingFederate console node.

  5. If PingFederate is running in a cluster, replicate the configuration to the engine nodes.