1. Ensure Oracle Server JRE (Java SE Runtime Environment) 8 is installed on the PingFederate server.
    To use larger key sizes, the Java Cryptography Extension (JCE) "unlimited strength" jurisdiction policy must be enabled. For more information, see Installing Java.
  2. Install and configure your Gemalto SafeNet Luna Network HSM, including the optional package for Java (referred to as the JSP), according to SafeNet's instructions.
    This includes the creation of a partition, creation of a Network Trust Link (NTL), and assignment of a client to a partition. Ensure that you can perform the vtl verify command indicating that you are communicating securely and properly to the HSM.

    Delete any unnecessary keys or objects that may have been created while testing communication to the HSM from the host that runs PingFederate.

    Note the password used to open communication to the HSM via the NTL. You need this for your PingFederate installation.

  3. 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.

    SafeNet provides some sample Java applications that may be run to ensure that the Java HSM interface is working properly prior to installing PingFederate. Please refer to the HSM documentation from Gemalto for more information.

  4. Update the JAVA_HOME/jre/lib/security/java.security file in your Java environment and add the LunaProvider line to the list of security providers, immediately before the sun.security.ec.SunEC provider; for example:
    # 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=com.safenetinc.luna.provider.LunaProvider
    security.provider.4=sun.security.ec.SunEC
    security.provider.5=com.sun.net.ssl.internal.ssl.Provider
    security.provider.6=com.sun.crypto.provider.SunJCE
    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
  5. Set up a new PingFederate installation on the network interconnected to the HSM.
    Important:

    Skip to the next step to integrate an existing PingFederate installation with your HSM.

  6. Update the hivemodule.xml file.
    1. Edit the hivemodule.xml file, located in the <pf_install>/pingfederate/server/default/conf/META-INF directory.
    2. Look for the <!-- Crypto provider --> section.
    3. Update the class attribute value of the construct element for both the JCEManager and CertificateService 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>
      ...
  7. Update the <pf_install>/pingfederate/bin/run.properties file.
    1. Change the value of the pf.hsm.mode property from OFF to LUNA.
    2. If you are setting up a new PingFederate installation, set the value of the pf.hsm.hybrid property to false. When set to false, as you create or import certificates (such as your signing certificate or your encryption key), the certificates are stored on your HSM.
      If you are configuring an existing PingFederate installation, set the value to true, which provides the flexibility to store each relevant key and certificate on the HSM or the local trust store. This capability allows you to transition the storage of keys and certificates to your HSM without the need to deploy a new PingFederate environment and to mirror the setup. For more information, see Transitioning to an HSM.
  8. 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 (see step 2).

    This procedure sets and securely stores the password for NTL communication to the HSM from PingFederate.

    Note:

    The Gemalto SafeNet Luna Network HSM may be configured in a high-availability group. To do so, please refer to the SafeNet distributed-installation instructions. To properly synchronize data, ensure that the HAOnly property is enabled using this command:

    vtl haAdmin –HAOnly –enable

  9. If you are setting up a new or configuring an existing PingFederate cluster, repeat these steps on each node.

This completes the steps required to configure PingFederate for use with Gemalto SafeNet Luna Network HSM. You may start the new PingFederate server or restart the existing PingFederate server.

Important:

To ensure expected behavior, SafeNet recommends restarting dependent processes such as PingFederate (including all server nodes in a cluster) whenever the Luna HSM is restarted.