--- title: Integrating with Thales Luna Network HSM description: PingFederate supports multiple hardware security modules (HSMs), including Thales Luna Network HSMs. component: pingfederate version: 13.0 page_id: pingfederate:getting_started_with_pingfederate:pf_integrating_thales_luna_network_hsm canonical_url: https://docs.pingidentity.com/pingfederate/13.0/getting_started_with_pingfederate/pf_integrating_thales_luna_network_hsm.html revdate: December 30, 2025 section_ids: steps: Steps --- # Integrating with Thales Luna Network HSM PingFederate supports multiple hardware security modules (HSMs), including Thales Luna Network HSMs. ## Steps 1. Ensure that the PingFederate server has a supported Java virtual machine (JVM) installed. Learn more in [Installing Java](../installing_and_uninstalling_pingfederate/pf_install_java.html). 2. Install and configure your Thales Luna Network HSM, including the optional JSP package for Java, according to Thales's instructions. This includes creating a partition, creating a Network Trust Link (NTL), and assigning a client to a partition. 1. Ensure the operation of the `vtl verify` command to indicate secure and proper communication with the HSM. 2. Delete any unnecessary keys or objects created while testing communication to the HSM from the host running PingFederate. 3. For your PingFederate installation, record the password used to open communication to the HSM through the NTL. 3. Update the `java.security` file in your Java environment by inserting `LunaProvider` after `SunJCE`, and then moving `SunRsaSign` and `SunEC` below `LunaProvider`. Ensure that the providers are numbered sequentially after your changes. * If the node uses Java 17 or 21, the `java.security` file is in the `JAVA_HOME/conf/security` directory. Here's an example of an updated file for Java 17: ``` # List of providers and their preference orders (see above): security.provider.1=SUN security.provider.2=SunJSSE security.provider.3=SunJCE security.provider.4=com.safenetinc.luna.provider.LunaProvider security.provider.5=SunRsaSign security.provider.6=SunEC security.provider.7=SunJGSS security.provider.8=SunSASL security.provider.9=XMLDSig security.provider.10=SunPCSC security.provider.11=JdkLDAP security.provider.12=JdkSASL security.provider.13=SunMSCAPI security.provider.14=SunPKCS11 ``` 4. On the network interconnected to the HSM, set up a new PingFederate installation. | | | | - | ---------------------------------------------------------------------------------------- | | | To integrate an existing PingFederate installation with your HSM, skip to the next step. | 5. To enable the Java interface, copy the Luna library and program files to the Java installation as follows. | Operating system | Steps | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Windows | Copy the `LunaAPI.dll` and `LunaProvider.jar` files from the `LUNA_HOME/jsp/lib` directory to the `/pingfederate/startup` directory. | | Linux | Copy the `libLunaAPI.so` and `LunaProvider.jar` files from the `LUNA_HOME/jsp/lib` directory to the `/pingfederate/startup` directory. | Prior to installing PingFederate, Thales provides sample Java applications to test that the Java HSM interface works. For more information, see the HSM documentation from Thales. 6. 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.LunaJCEManager ... certificate.service=com.pingidentity.crypto.LunaCertificateServiceImpl ... ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | 7. In `com.pingidentity.crypto.LunaPartitions.xml`, configure `DefaultPartitionSlotOrLabel` with the slot number or label associated with the HSM partition you created in [\[step1\]](#step1). 8. Update the `/pingfederate/bin/run.properties` file. 1. Change the value of `pf.hsm.mode` from `OFF` to `LUNA`. 2. To configure a new PingFederate installation, set the value of `pf.hsm.hybrid` to `false`. When set to `false`, the HSM stores newly created or imported certificates. To configure 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). 9. From the `/pingfederate/bin` directory, run the `hsmpass.bat` batch file for Windows or the `hsmpass.sh` script for Linux. 1. Enter the NTL password when prompted. For more information, see [\[step1\]](#step1). This procedure securely stores the password for NTL communication to the HSM from PingFederate. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The Thales Luna Network HSM supports configuration in a high-availability group. For more information, see the Thales distributed-installation instructions. To properly synchronize data, ensure that the `HAOnly` property is enabled using the `vtl haAdmin –HAOnly –enable` command. | 10. Repeat these steps on each node. 11. Start the new PingFederate server or restart the existing PingFederate server. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------- | | | Whenever you restart the Luna HSM, Thales recommends you also restart dependent processes such as PingFederate and all server nodes in a cluster. |