PingFederate Server

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.

  6. If PingFederate is running with the active/passive admin node feature enabled, the passive admin nodes will automatically update with changes to keys stores in pf.jwk. No admin actions are necessary.