PingFederate supports multiple hardware security modules (HSMs), including Thales Luna Network HSMs.
Ensure that the PingFederate server has a supported
Java virtual machine (JVM) installed.
For more information, see Installing Java.
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.
- Ensure the operation of the vtl verify command to indicate secure and proper communication with the HSM.
- Delete any unnecessary keys or objects created while testing communication to the HSM from the host running PingFederate.
- For your PingFederate installation, record the password used to open communication to the HSM through the NTL.
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 <pf_install>/pingfederate/startup directory. Linux Copy the libLunaAPI.so and LunaProvider.jar files from the LUNA_HOME/jsp/lib directory to the <pf_install>/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.
Update the java.security file in your Java environment by
SunJCE, and then moving
LunaProvider. Ensure that the providers are numbered sequentially after your changes.
- If the node uses Java 8, the java.security file is in the
JAVA_HOME/jre/lib/security directory. Here's an example
of an updated file for Java
# List of providers and their preference orders (see above): security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.net.ssl.internal.ssl.Provider security.provider.3=com.sun.crypto.provider.SunJCE security.provider.4=com.safenetinc.luna.provider.LunaProvider security.provider.5=sun.security.rsa.SunRsaSign security.provider.6=sun.security.ec.SunEC 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
- If the node uses Java 11, the java.security file is in
the JAVA_HOME/conf/security directory. Here's an example
of an updated file for Java
# 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=SunPKCS11
- If the node uses Java 8, the java.security file is in the JAVA_HOME/jre/lib/security directory. Here's an example of an updated file for Java 8:
On the network interconnected to the HSM, set up a new PingFederate
To integrate an existing PingFederate installation with your HSM, skip to the next step.
Go to the
# Crypto provider servicessection.
certificate.serviceservice 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.
- Go to the
DefaultPartitionSlotOrLabelwith the slot number or label associated with the HSM partition you created in step 2.
Change the value of pf.hsm.mode from
To configure a new PingFederate installation, set the value of
false. When set to
false, the HSM stores newly created or imported certificates.To configure an existing PingFederate installation, set the value to
truefor 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 pf.hsm.mode from
directory, run the hsmpass.bat batch file for Windows or the
hsmpass.sh script for Linux.
Enter the NTL password when prompted. For more information, see step 2.
This procedure securely stores the password for NTL communication to the HSM from PingFederate.Note:
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.
- Enter the NTL password when prompted. For more information, see step 2.
- Repeat these steps on each node.
Start the new PingFederate server or restart the existing PingFederate
Whenever you restart the Luna HSM, Thales recommends you also restart dependent processes such as PingFederate and all server nodes in a cluster.