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
inserting
LunaProvider
afterSunJCE
, and then movingSunRsaSign
andSunEC
belowLunaProvider
. 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
8:
# 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
11:
# List of providers and their preference orders (see above): security.provider.1=SUN security.provider.2=SunRsaSign security.provider.3=SunEC security.provider.4=SunJSSE security.provider.5=SunJCE security.provider.6=com.safenetinc.luna.provider.LunaProvider 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
installation.
Note:
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
JCEManager
andCertificateService
service 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> ...
-
In
com.pingidentity.crypto.LunaPartitions.xml
, configureDefaultPartitionSlotOrLabel
with the slot number or label associated with the HSM partition you created in step 2. -
Update the
<pf_install>/pingfederate/bin/run.properties
file.
-
Change the value of pf.hsm.mode from
OFF
toLUNA
. -
To configure a new PingFederate installation, set the value of
pf.hsm.hybrid to
false
. When set tofalse
, the HSM stores newly created or imported certificates.To configure an existing PingFederate installation, set the value totrue
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.
-
Change the value of pf.hsm.mode from
-
From the
<pf_install>/pingfederate/bin
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
server.
Important:
Whenever you restart the Luna HSM, Thales recommends you also restart dependent processes such as PingFederate and all server nodes in a cluster.