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

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

  2. Install and configure your AWS CloudHSM client and tools.
    Note:

    Commands vary depending on the operating system. For more information, see Install the AWS CloudHSM Client and Command Line Tools in the AWS CloudHSM documentation.

  3. Install the AWS CloudHSM software library for Java.
    Note:

    Commands vary depending on the Linux operating system. For instructions, see Installing Java Library in the AWS CloudHSM documentation.

  4. 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 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, see Validating the Installation in the AWS CloudHSM documentation.

  5. Update the JAVA_HOME/jre/lib/security/java.security file in your Java environment, and then add the AWSCloudHSMProvider line to the list of security providers immediately after the sun.security.provider.Sun provider. 
    # 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
  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 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
  8. Update the hivemodule.xml file.
    1. Edit the <pf_install>/pingfederate/server/default/conf/META-INF/hivemodule.xml file.
    2. Go to the <!-- Crypto provider --> section.
    3. Update the class attribute value of the construct element for both the JCEManager and CertificateService service endpoint. 
      ...
<!-- 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>
...
  9. 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.
  10. Run the <pf_install>/pingfederate/bin/hsmpass.sh script for Linux.
    1. Enter the password for the CU account when prompted. See step 1.
      This procedure securely stores the password for communication to the HSM from PingFederate.
  11. 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 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">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>
  12. Repeat these steps on each node.
  13. Start the new PingFederate server or restart the existing PingFederate server.