Administrators can enable the HSM hybrid mode, which provides the choice to store each relevant key and certificate on an HSM or the PingFederate-managed local trust store. This capability allows organizations to transition the storage of keys and certificates to a supported HSM to meet security requirements without the need to deploy a new PingFederate environment and mirror the setup.

The following images illustrate some general interactions between PingFederate and an HSM. Those interactions depend on whether you configure the HSM in hybrid mode.

Flowchart of interaction between PingFederate and HSM not in hybrid mode

Flowchart of interaction between PingFederate and HSM in hybrid mode

Note:

For a list of supported HSMs, see the "Hardware security modules" section under "Third-party cryptographic solutions" in System requirements.

When all relevant keys and certificates are stored on the HSM, administrators can turn off the HSM hybrid mode. When the HSM hybrid mode is disabled, PingFederate delegates the management of the relevant keys and certificates to the HSM.
Important:

After the HSM hybrid mode is disabled, for keys and certificates that should be stored on an HSM, PingFederate will only access those keys and certificates from the HSM, regardless of whether such keys and certificates exist on the local trust store.

  1. Install and configure the HSM client and the existing PingFederate environment. See Supported hardware security modules.
    Important:

    When editing the <pf_install>/pingfederate/bin/run.properties file, set the pf.hsm.hybrid property to true to enable the HSM hybrid mode.

    After PingFederate is integrated with your HSM, you can create (and store) new certificates on your HSM. Because the HSM hybrid mode is enabled, you can reconfigure connections or other configuration items to use the new certificates over a period of time. As long as the HSM hybrid mode is enabled, PingFederate can use certificates stored on your HSM and the local trust store.

    Important:

    When making changes to keys and certificates, you might need to coordinate with your partners. For more information, see Digital signing policy coordination.

  2. Create a new SSL server certificate on your HSM and activate it for the administrative console and the runtime server on Security > Certificate & Key Management > SSL Server Certificates.
    Note:

    You can also create separate certificates on your HSM and activate one certificate for the administrative console and the other certificate for the runtime server. For configuration steps, see Manage SSL server certificates.

  3. Create new digital signing certificates and decryption keys on Security > Certificate & Key Management > Signing & Decryption Keys & Certificates and reconfigure connections or configuration items to use the new certificates and keys from your HSM.
    Tip:

    Use Check Usage to locate the applicable connections or configuration items.

    For configuration steps, see Manage digital signing certificates and decryption keys.

  4. If your connections support outbound (SOAP) back-channel authentication by client certificates, create new SSL client certificates on Security > Certificate & Key Management > SSL Client Keys & Certificates and reconfigure connections to use the new certificates from your HSM.
    Tip:

    Use Check Usage to locate the applicable connections or configuration items.

    For configuration steps, see Manage SSL client keys and certificates.

  5. If you are transitioning to an Entrust HSM, export the trusted certificate authority (CA) certificates from the local trust store and import them to your HSM on Security > Certificate & Key Management > Trusted CAs and reconfigure configuration items to use the new certificates and keys from your HSM.
    Tip:

    Use Check Usage to locate the applicable configuration items.

    For configuration steps, see Manage trusted certificate authorities.

  6. If you are transitioning to an Entrust HSM, for connections using the unanchored trust model, export the partner certificate for back-channel authentication from the local trust store, import them to your HSM, and reconfigure the connections to use the new certificates from your HSM. For information about the unanchored trust model, see "Trust models" under Digital signing policy coordination.

    For configuration steps, see Managing certificates from partners+.