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