--- title: Integrating with AWS CloudHSM description: PingFederate supports multiple hardware security modules (HSMs), including Amazon Web Services (AWS) CloudHSM. component: pingfederate version: 13.1 page_id: pingfederate:getting_started_with_pingfederate:pf_integra_aws_cloudhsm canonical_url: https://docs.pingidentity.com/pingfederate/13.1/getting_started_with_pingfederate/pf_integra_aws_cloudhsm.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: November 10, 2025 section_ids: before-you-begin: Before you begin steps: Steps choose-from: Choose from: choose-from-2: Choose from: choose-from-3: Choose from: example: Example: --- # Integrating with AWS CloudHSM PingFederate supports multiple hardware security modules (HSMs), including Amazon Web Services (AWS) *(tooltip: \
\

An Amazon subsidiary providing cloud computing platforms.\

\
)* CloudHSM. ## Before you begin * Ensure that Java 17 or 21 is installed on the PingFederate server. Learn more in [Installing Java](../installing_and_uninstalling_pingfederate/pf_install_java.html). * PingFederate must be deployed on one of the operating systems supported by both AWS CloudHSM and PingFederate. See [System requirements](../installing_and_uninstalling_pingfederate/pf_system_requirements.html) and [Supported platforms for the client SDKs](https://docs.aws.amazon.com/cloudhsm/latest/userguide/client-supported-platforms.html) 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 1. Request a crypto user (CU) account from your AWS CloudHSM administrator. You need this account's username and password for your PingFederate installation. 2. Install and configure the AWS CloudHSM Java Cryptography Extension (JCE) provider for Client SDK 5. Learn more in [Install and use the AWS CloudHSM JCE provider for Client SDK 5](https://docs.aws.amazon.com/cloudhsm/latest/userguide/java-library-install_5.html) 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. | 3. Connect the Client SDK to the AWS CloudHSM cluster. For instructions, see [Bootstrap the Client SDK](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cluster-connect.html#connect-how-to) in the AWS CloudHSM documentation. 4. 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. 5. 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. 6. 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. | 7. To enable the Java interface and PingFederate integration, copy the `cloudhsm-jce-5.6.0.jar` file to the `pingfederate/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`. | 8. 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`. 9. Edit the `/pingfederate/server/default/conf/service-points.conf` file. 1. Go to the `# Crypto provider services` section. 2. Change the `jce.manager` and `certificate.service` service endpoints to the following: ``` ... jce.manager=com.pingidentity.crypto.AWSCloudHSMJCEManager ... certificate.service=com.pingidentity.crypto.AWSCloudHSMCertificateServiceImpl ... ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | 10. Update the `/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](../administrators_reference_guide/pf_transition_to_hsm.html). 11. Run: ### Choose from: * The `/pingfederate/bin/hsmpass.sh` script on Linux operating systems. * The `/pingfederate/bin/hsmpass.bat` command on Windows operating systems. 12. 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. 13. If the username of the CU account is not `crypto_user`, update the `com.pingidentity.crypto.AWSCloudHSM.xml` file: 1. Edit the `/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 PARTITION_1 crypto_user ``` 2. 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 PARTITION_1 example_user ``` 14. Repeat these steps on each node. 15. Start the new PingFederate server or restart the existing PingFederate server.