1. Ensure Oracle Server JRE (Java SE Runtime Environment) 8 is installed on the PingFederate server.
    For more information, see Installing Java.

    Additionally, PingFederate must be deployed on one of the Linux operating systems supported by both AWS CloudHSM and PingFederate. For more information, see System requirements and Install and Configure the AWS CloudHSM Client (Linux) in the AWS CloudHSM documentation (docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html).

  2. Request a crypto user (CU) account from your AWS CloudHSM administrator.
    You need both the username (for example, crypto_user) and the password of this account for your PingFederate installation.
  3. Install and configure your AWS CloudHSM client and tools.
    Commands vary depending on the operating system. For more information, refer to Install the AWS CloudHSM Client and Command Line Tools in the AWS CloudHSM documentation (docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html).
  4. Install AWS CloudHSM software library for Java.
    Commands vary depending on the Linux operating system. For instructions, refer to Installing Java Library in the AWS CloudHSM documentation (docs.aws.amazon.com/cloudhsm/latest/userguide/java-library-install.html#install-java-library).
  5. Validate the AWS CloudHSM client installation.
    1. Using the command line, export four environment variables.
      $ export LD_LIBRARY_PATH=/opt/cloudhsm/lib
      $ export HSM_PARTITION=PARTITION_1
      $ export HSM_USER=<HSM username>
      $ export HSM_PASSWORD=<password>
    2. To validate the AWS CloudHSM client installation, run the following Java program.
      $ java -classpath "/opt/cloudhsm/java/*" org.junit.runner.JUnitCore TestBasicFunctionality

      The result should be similar to the following sample output.

      JUnit version 4.12
      .2020-02-24 16:17:01,681 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:33) - Adding provider.
      2020-02-24 16:17:01,749 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:42) - Logging in.
      2020-02-24 16:17:01,749 INFO  [main] cfm2.LoginManager (LoginManager.java:238) - Looking for credentials in HsmCredentials.properties
      2020-02-24 16:17:01,750 INFO  [main] cfm2.LoginManager (LoginManager.java:256) - Looking for credentials in System.properties
      2020-02-24 16:17:01,750 INFO  [main] cfm2.LoginManager (LoginManager.java:264) - Looking for credentials in System.env
      2020-02-24 16:17:01,784 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:54) - Generating AES Key with key size 256.
      2020-02-24 16:17:01,995 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:63) - Encrypting with AES Key.
      2020-02-24 16:17:02,005 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:84) - Deleting AES Key.
      2020-02-24 16:17:02,006 DEBUG [main] TestBasicFunctionality (TestBasicFunctionality.java:92) - Logging out.
      
      Time: 0.334
      
      OK (1 test)

      For more information, refer to Validating the Installation in the AWS CloudHSM documentation (docs.aws.amazon.com/cloudhsm/latest/userguide/java-library-install.html#validate-install).

  6. Update the JAVA_HOME/jre/lib/security/java.security file in your Java environment and add the AWSCloudHSMProvider line to the list of security providers, immediately after the sun.security.provider.Sun provider; for example:
    # List of providers and their preference orders (see above):
    security.provider.1=sun.security.provider.Sun
    security.provider.2=com.pingidentity.crypto.AWSCloudHSMProvider
    security.provider.3=sun.security.rsa.SunRsaSign
    security.provider.4=sun.security.ec.SunEC
    security.provider.5=com.sun.net.ssl.internal.ssl.Provider
    security.provider.6=com.sun.crypto.provider.SunJCE
    security.provider.7=sun.security.jgss.SunProvider
    security.provider.8=com.sun.security.sasl.Provider
    security.provider.9=org.jcp.xml.dsig.internal.dom.XMLDSigRI
    security.provider.10=sun.security.smartcardio.SunPCSC
  7. Set up a new PingFederate installation on the network interconnected to the HSM.
    Important:

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

  8. To enable the Java interface and PingFederate integration, copy the following files to the JAVA_HOME/jre/lib/ext directory.
    • <pf_install>/pingfederate/lib-ext/pf-aws-cloud-hsm-wrapper.jar
    • <pf_install>/pingfederate/server/default/lib/disruptor.jar
    • All files under the /opt/cloudhsm/java directory
    • All files under the /opt/cloudhsm/lib directory
  9. Update the hivemodule.xml file.
    1. Edit the hivemodule.xml file, located in the <pf_install>/pingfederate/server/default/conf/META-INF directory.
    2. Look for the <!-- Crypto provider --> section.
    3. Update the class attribute value of the construct element for both the JCEManager and CertificateService service endpoint as follows.
      ...
      <!-- Crypto provider -->
      <service-point id="JCEManager" interface="com.pingidentity.crypto.JCEManager">
      	<invoke-factory>
      		...
      		<construct class="com.pingidentity.crypto.AWSCloudHSMJCEManager"/>
      	</invoke-factory>
      </service-point>
      
      <service-point id="CertificateService" interface="com.pingidentity.crypto.CertificateService">
      	<invoke-factory>
      		...
      		<construct class="com.pingidentity.crypto.AWSCloudHSMCertificateServiceImpl"/>
      	</invoke-factory>
      </service-point>
      ...
  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. When set to false, as you create or import certificates (such as your signing certificate or your encryption key), the certificates are stored on your HSM.
      If you are configuring an existing PingFederate installation, set the value to true, which provides the flexibility to store each relevant key and certificate on the HSM or the local trust store. This capability allows you to transition the storage of keys and certificates to your HSM without the need to deploy a new PingFederate environment and to mirror the setup. For more information, see Transitioning to an HSM.
  11. From the <pf_install>/pingfederate/bin directory, run the hsmpass.sh script for Linux.
    Enter the password for the CU account when prompted (see step 2).

    This procedure sets and securely stores the password for communication to the HSM from PingFederate.

  12. If the username of the CU account is not crypto_user, update the com.pingidentity.crypto.AWSCloudHSM.xml file.
    1. Edit the com.pingidentity.crypto.AWSCloudHSM.xml file, located in the <pf_install>/pingfederate/server/default/data/config-store directory.
      The unmodified version of the com.pingidentity.crypto.AWSCloudHSM.xml file reads:
      <?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.

      For example, if the username of the CU account is example_user, update as follows.

      <?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>
  13. If you are setting up a new or configuring an existing PingFederate cluster, repeat these steps on each node.

This completes the steps required to configure PingFederate for use with AWS CloudHSM. You may start the new PingFederate server or restart the existing PingFederate server.