Administrators may enable the HSM hybrid mode, which provides the choice to store each relevant key and certificate on a hardware security module (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 to mirror the setup.

Note:

PingFederate supports the following HSMs:

  • AWS CloudHSM (stores private keys only)
  • Gemalto SafeNet Luna Network HSM (stores private keys only)
  • nCipher nShield Connect HSM (stores both certificates and private keys)
When all relevant keys and certificates are stored on the HSM, administrators may 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:

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

    Once PingFederate is integrated with your HSM, you can create (and store) new certificates on your HSM. Because the HSM hybrid mode is enabled, you may 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 that are stored on your HSM and the local trust store.

    Important:

    When making changes to keys and certificates, you may 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 the Security > SSL Server Certificates screen.
    You may 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 Managing SSL server certificates.

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

    You may use Check Usage to locate the applicable connections or configuration items.

    For configuration steps, see Managing 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 the Security > SSL Client Keys & Certificates screen and reconfigure connections to use the new certificates from your HSM.
    Tip:

    You may use Check Usage to locate the applicable connections or configuration items.

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

  5. If you are transitioning to an nCipher HSM, export the trusted CA certificates from the local trust store and import them to your HSM on the Security > Trusted CAs screen and reconfigure configuration items to use the new certificates and keys from your HSM.
    Tip:

    You may use Check Usage to locate the applicable configuration items.

    For configuration steps, see Managing trusted certificate authorities.

  6. If you are transitioning to an nCipher 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.