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 nCipher nShield Connect HSM client software.
    As part of the installation, install the optional Java Support (including KeySafe) and nCipherKM JCA/JCE provider classes components.
  3. After your installation, refer to the HSM documentation from nCipher to see how to make your PingFederate server a client of an HSM server.
    Note:

    PingFederate only supports Operator Card Set (OCS) protected keys. Note the password used for the OCS; you will need the password for your installation of PingFederate.

  4. To enable the Java interface, copy the NFAST_HOME/java/classes/nCipherKM.jar file to the JAVA_HOME/jre/lib/ext directory.
    nCipher 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 nCipher for more information.
  5. Update the JAVA_HOME/jre/lib/security/java.security file in your Java environment and add the nCipherKM line to the list of security providers, after all the sun providers; 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=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=sun.security.mscapi.SunMSCAPI
security.provider.11=com.ncipher.provider.km.nCipherKM
  6. 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.

  7. 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.NcipherJCEManager"/>
	</invoke-factory>
</service-point>

<service-point id="CertificateService" interface="com.pingidentity.crypto.CertificateService">
	<invoke-factory>
		...
		<construct class="com.pingidentity.crypto.NcipherCertificateServiceImpl"/>
	</invoke-factory>
</service-point>
...
  8. Update the <pf_install>/pingfederate/bin/run.properties file.
    1. Change the value of the pf.hsm.mode property from OFF to NCIPHER.
    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.
  9. From the <pf_install>/pingfederate/bin directory, run the hsmpass.bat batch file for Windows or the hsmpass.sh script for Linux.
    Enter the Operator Card Set password when prompted (see step 3).

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

  10. If you are setting up a new or configuring an existing PingFederate cluster, repeat these steps on each node.
    When finished, use the following steps to replicate nShield data to the connected nodes in the cluster.
    1. On the console node, locate the <pf_install>/pingfederate/server/default/data directory and create a sub directory named ncipher-kmdata-local.
    2. Copy to the ncipher-kmdata-local directory all files from the NFAST_KMDATA\local directory, where NFAST_KMDATA is an environment variable created during the nShield Connect installation.
      For example, NFAST_KMDATA could be set to C:\ProgramData\nCipher\Key Management Data.
    3. Create a new environment variable named NFAST_KMLOCAL and set it to <pf_install>/pingfederate/server/default/data/ncipher-kmdata-local
      Note:

      You must perform define this environment variable on all servers within the cluster.

    4. Restart the nShield Connect hardserver on all PingFederate servers in the cluster. (See the HSM documentation from nCipher for instructions on restarting the hardserver.)
    5. Log on to the PingFederate administrative console, go to the System > Cluster Management screen and then click Replicate Configuration to push the configuration changes, which includes the nShield data, to the engine nodes.

This completes the steps required to configure PingFederate for use with nCipher nShield Connect HSM. You may start the new PingFederate server or restart the existing PingFederate server.

Important:

To ensure expected behavior, PingFederate (including all server nodes in a cluster) should be restarted whenever the nShield HSM is restarted.