-
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).
-
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.
-
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).
-
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).
-
Validate the AWS CloudHSM client installation.
-
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>
-
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).
-
Using the command line, export four environment variables.
-
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 thesun.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
-
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.
-
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
-
Update the hivemodule.xml file.
- Edit the hivemodule.xml file, located in the <pf_install>/pingfederate/server/default/conf/META-INF directory.
-
Look for the
<!-- Crypto provider -->
section. -
Update the class attribute value of the
construct element for both the
JCEManager
andCertificateService
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> ...
-
Update the
<pf_install>/pingfederate/bin/run.properties
file.
-
Change the value of the pf.hsm.mode property from
OFF
toAWSCLOUDHSM
. -
If you are setting up a new PingFederate installation, set the value of the
pf.hsm.hybrid property to
false
. When set tofalse
, 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 totrue
, 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.
-
Change the value of the pf.hsm.mode property from
-
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.
-
If the username of the CU account is not crypto_user, update the
com.pingidentity.crypto.AWSCloudHSM.xml file.
-
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>
-
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>
-
Edit the com.pingidentity.crypto.AWSCloudHSM.xml file,
located in the
<pf_install>/pingfederate/server/default/data/config-store
directory.
- 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.