• Ensure that Java 8 or 11 is installed on the PingFederate server. For more information, see Installing Java.
  • PingFederate must be deployed on one of the operating systems supported by both AWS CloudHSM and PingFederate. See System requirements and Supported platforms for the client SDKs in the AWS CloudHSM documentation for a list of mutually supported operating systems.
Note:

As of version 11.2, PingFederate will no longer support the AWS CloudHSM Client SDK 3.

  1. Request a crypto user (CU) account from your AWS CloudHSM administrator.

    You need this account's username and password for your PingFederate installation.

  2. Install and configure the AWS CloudHSM Java Cryptography Extension (JCE) provider for Client SDK 5. For more information, see Install and use the AWS CloudHSM JCE provider for Client SDK 5 in the AWS CloudHSM documentation.
    Important:

    To ensure successful installation of the JCE provider, do not install the AWS CloudHSM client. If you are upgrading from PingFederate 11.1 or earlier, remove any existing CloudHSM client software.

  3. Connect the Client SDK to the AWS CloudHSM cluster. For instructions, see Bootstrap the Client SDK in the AWS CloudHSM documentation.
  4. Run the appropriate command for your operating system to ensure that keys are available to use even if a cluster not containing multiple HSMs is used:
    • On Linux operating systems, run the sudo /opt/cloudhsm/bin/configure-jce --disable-key-availability-check command.
    • On Windows operating systems, run the C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe --disable-key-availability-check command.
  5. If you plan to use elliptic curve (EC) keys for decryption, run the appropriate command for your operating system.
    • On Linux operating systems, run the sudo /opt/cloudhsm/bin/configure-jce --enable-ecdh-without-kdf command.
    • On Windows operating systems, run the C:\Program Files\Amazon\CloudHSM\bin\configure-jce.exe --enable-ecdh-without-kdf command.
  6. Configure a new PingFederate installation on the network interconnected to the HSM.
    Note:

    Go to the next step to integrate an existing PingFederate installation with your HSM.

  7. To enable the Java interface and PingFederate integration, copy the cloudhsm-jce-5.6.0.jar file to the pingfederate/startup directory:
    Note:
    • On Linux operating systems, the file location is/opt/cloudhsm/java/cloudhsm-jce-5.6.0.jar.
    • On Windows operating systems, the file location is C:\Program Files\Amazon\CloudHSM\java\cloudhsm-jce-5.6.0.jar.
  8. If you are upgrading from PingFederate 11.1 or earlier, revert any previous changes to the JAVA_HOME/jre/lib/security/java.security file and remove the pf-aws-cloud-hsm-wrapper.jar and other files previously copied to JAVA_HOME/jre/lib/ext.
  9. Edit the <pf_install>/pingfederate/server/default/conf/service-points.conf file.
    1. Go to the # Crypto provider services section.
    2. Change the jce.manager and certificate.service service endpoints to the following: 
      ...
jce.manager=com.pingidentity.crypto.AWSCloudHSMJCEManager
...
certificate.service=com.pingidentity.crypto.AWSCloudHSMCertificateServiceImpl
...
    Note:

    In clustered PingFederate environments, you must manually edit the service-points.conf file on each node because cluster replication can't replicate this change to other nodes.

  10. Update the <pf_install>/pingfederate/bin/run.properties file:
    1. Change the value of the pf.hsm.mode property from OFF to AWSCLOUDHSM.
    2. If you are setting up a new PingFederate installation, set the value of the pf.hsm.hybrid property to false to store newly-created or imported certificates on your HSM.
    3. If you are configuring an existing PingFederate installation, set the value to true for the flexibility to store each relevant key and certificate on the HSM or the local trust store.

      This allows you to transition the storage of keys and certificates to your HSM without deploying a new PingFederate environment. For more information, see Transitioning to an HSM.

  11. Run:
    • The <pf_install>/pingfederate/bin/hsmpass.sh script on Linux operating systems.
    • The <pf_install>/pingfederate/bin/hsmpass.bat command on Windows operating systems.
  12. Enter the password for the CU account that you requested in step 1 when prompted.
    This procedure securely stores the password for communication to the HSM from PingFederate.
  13. If the username of the CU account is not crypto_user, update the com.pingidentity.crypto.AWSCloudHSM.xml file:
    1. Edit the <pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.crypto.AWSCloudHSM.xml file.

      The unmodified version of the com.pingidentity.crypto.AWSCloudHSM.xml file is shown in the following:

      <?xml version="1.0" encoding="UTF-8"?>
<con:config xmlns:con="http://www.sourceid.org/2004/05/config">
    <con:item name="Partition">PARTITION_1</con:item>
    <con:item name="CryptoUser">crypto_user</con:item>
</con:config>
    2. Replace crypto_user with the username of the CU account.

      In the following example, the username of the CU account is example_user. 

      <?xml version="1.0" encoding="UTF-8"?>
<con:config xmlns:con="http://www.sourceid.org/2004/05/config">
    <con:item name="Partition">PARTITION_1</con:item>
    <con:item name="CryptoUser">example_user</con:item>
</con:config>
  14. Repeat these steps on each node.
  15. Start the new PingFederate server or restart the existing PingFederate server.