Integrating with AWS CloudHSM
PingFederate supports multiple hardware security modules (HSMs), including Amazon Web Services (AWS) CloudHSM.
Before you begin
-
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. |
Steps
-
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.
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:
Choose from:
-
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.
-
-
If you plan to use elliptic curve (EC) keys for decryption, run the appropriate command for your operating system.
Choose from:
-
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.
-
-
Configure a new PingFederate installation on the network interconnected to the HSM.
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 thepingfederate/startup
directory:-
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 thepf-aws-cloud-hsm-wrapper.jar
and other files previously copied toJAVA_HOME/jre/lib/ext
. -
Update the
hivemodule.xml
file:-
Edit the
<pf_install>/pingfederate/server/default/conf/hivemodule.xml
file. -
Go to the
<!-- Crypto provider -→
section. -
Update the
class
attribute value of theconstruct
element for both theJCEManager
andCertificateService
service endpoint.Example:
... <!-- 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 fromOFF
toAWSCLOUDHSM
. -
If you are setting up a new PingFederate installation, set the value of the
pf.hsm.hybrid
property tofalse
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.
-
-
Run:
Choose from:
-
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 thecom.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.Example:
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>
-
-
Repeat these steps on each node.
-
Start the new PingFederate server or restart the existing PingFederate server.