PingFederate supports multiple hardware security
modules (HSMs), including
- 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.
As of version 11.2, PingFederate will no longer support the AWS CloudHSM Client SDK 3.
-
Request a crypto user (CU) account from your AWS CloudHSM administrator.
You need this account's username and password for your PingFederate installation.
-
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.
- Connect the Client SDK to the AWS CloudHSM cluster. For instructions, see Bootstrap the Client SDK in the AWS CloudHSM documentation.
-
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.
- On Linux operating systems, run the
-
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.
- On Linux operating systems, run the
-
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.
-
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.
- 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.
-
Edit the
<pf_install>/pingfederate/server/default/conf/service-points.conf
file.
-
Go to the
# Crypto provider services
section. -
Change the
jce.manager
andcertificate.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.
-
Go to the
-
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
to store newly-created or imported certificates on your HSM. -
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.
-
Change the value of the pf.hsm.mode property from
-
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.
-
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.
-
If the username of the CU account is not
crypto_user
, update the com.pingidentity.crypto.AWSCloudHSM.xml file:-
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>
-
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>
-
Edit the
<pf_install>/pingfederate/server/default/data/config-store/com.pingidentity.crypto.AWSCloudHSM.xml
file.
- Repeat these steps on each node.
- Start the new PingFederate server or restart the existing PingFederate server.