When PingFederate accumulates configuration encryption keys that are no longer needed for decryption, you can delete them.
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
<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
- The Unix timestamp format from the pf.jwk file, which looks
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
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:
- Stop the PingFederate console node.
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.
The utility displays its usage help.
deletecommand 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.
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"
- Restart the PingFederate console node.
- If PingFederate is running in a cluster, replicate the configuration to the engine nodes.