Integrating with Thales Luna Network HSM
PingFederate supports multiple hardware security modules (HSMs), including Thales Luna Network HSMs.
Steps
-
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.
-
-
Update the
java.security
file in your Java environment by insertingLunaProvider
afterSunJCE
, and then movingSunRsaSign
andSunEC
belowLunaProvider
. Ensure that the providers are numbered sequentially after your changes.-
If the node uses Java 11, the
java.security
file is in theJAVA_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 17, the
java.security
file is in theJAVA_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=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=SunMSCAPI security.provider.14=SunPKCS11
-
-
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.
-
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
andLunaProvider.jar
files from theLUNA_HOME/jsp/lib
directory to the<pf_install>/pingfederate/startup
directory.Linux
Copy the
libLunaAPI.so
andLunaProvider.jar
files from theLUNA_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.
-
Edit the
<pf_install>/pingfederate/server/default/conf/service-points.conf
file.-
Go to the
# Crypto provider services
section. -
Change the
jce.manager
andcertificate.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.
-
-
In
com.pingidentity.crypto.LunaPartitions.xml
, configureDefaultPartitionSlotOrLabel
with the slot number or label associated with the HSM partition you created in [step1]. -
Update the
<pf_install>/pingfederate/bin/run.properties
file.-
Change the value of
pf.hsm.mode
fromOFF
toLUNA
. -
To configure a new PingFederate installation, set the value of
pf.hsm.hybrid
tofalse
. When set tofalse
, 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. -
-
From the
<pf_install>/pingfederate/bin
directory, run thehsmpass.bat
batch file for Windows or thehsmpass.sh
script for Linux.-
Enter the NTL password when prompted. For more information, see [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 thevtl haAdmin –HAOnly –enable
command. -
-
Repeat these steps on each node.
-
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.