PingFederate supports multiple hardware security modules (HSMs), including Thales Luna Network HSMs.
Ensure the PingFederate server has Oracle Server JRE 8 installed.
To use larger key sizes, enable the Java Cryptography Extension (JCE) "unlimited strength" jurisdiction policy. 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 LUNA_HOME\jsp\lib\LunaAPI.dll file to an arbitrary directory and add the directory's path as a system variable. Alternatively, you can copy the file to the Windows system directory (C:\Windows\System32).
Copy the LUNA_HOME\jsp\lib\LunaProvider.jar file to the JAVA_HOME\jre\lib\ext directory.
Linux Copy the libLunaAPI.so and LunaProvider.jar files from the LUNA_HOME/jsp/lib directory to the JAVA_HOME/jre/lib/ext 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_HOME/jre/lib/security/java.security file in
your Java environment and add the
LunaProviderline to the bottom of the list of security providers.
# List of providers and their preference orders (see above): security.provider.1=sun.security.provider.Sun security.provider.2=sun.security.rsa.SunRsaSign security.provider.3=sun.security.ec.SunEC security.provider.4=com.sun.net.ssl.internal.ssl.Provider security.provider.5=com.sun.crypto.provider.SunJCE security.provider.6=sun.security.jgss.SunProvider security.provider.7=com.sun.security.sasl.Provider security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI security.provider.9=sun.security.smartcardio.SunPCSC security.provider.10=com.safenetinc.luna.provider.LunaProvider
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.
Update the hivemodule.xml file.
- Edit the <pf_install>/pingfederate/server/default/conf/META-INF/hivemodule.xml file.
Go to the
<!-- Crypto provider -->section.
Update the class attribute value of the
construct element for both the
CertificateServiceservice endpoint as follows.
... <!-- Crypto provider --> <service-point id="JCEManager" interface="com.pingidentity.crypto.JCEManager"> <invoke-factory> ... <construct class="com.pingidentity.crypto.LunaJCEManager"/> </invoke-factory> </service-point> <service-point id="CertificateService" interface="com.pingidentity.crypto.CertificateService"> <invoke-factory> ... <construct class="com.pingidentity.crypto.LunaCertificateServiceImpl"/> </invoke-factory> </service-point> ...
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.
Add the following line at the end of the file:
- 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.