PingFederate
This guide outlines step-by-step instructions for seamlessly integrating PingFederate with a Luna HSM device or Luna Cloud HSM service. PingFederate simplifies and enhances identity and access management, providing a single point of control for secure, seamless access to applications and services. Customers can streamline user authentication, improve security, and deliver a better user experience, all while reducing the complexity of managing identity and access across their organization.
The key benefits of this integration are:
-
Secure generation, storage, and protection of the identity signing private keys using either FIPS 140-2 or FIPS 140-3 Level 3 validated hardware.
-
Full life cycle management of the keys to ensure their integrity and reliability throughout their usage.
-
Maintenance of a comprehensive HSM audit trail for transparency and accountability in key operations. It's important to note that Luna Cloud HSM service does not have access to this secure audit trail.
-
Significant performance enhancements by offloading cryptographic operations from application servers.
Supported Platforms
This integration has been tested and verified on the following platforms:
| HSM Type | Platform Tested | Ping Federate Version |
|---|---|---|
| Luna HSM version 7.7.0 with firmware 7.7.0 and Luna Client 10.3.0 |
RHEL 8.2 | PingFedrate version 10.3 |
| Luna HSM version 7.2.0 with firmware 7.2.0 and Luna Client 7.2.0 |
RHEL 7.6 Windows Server 2016 Standard |
PingFedrate version 9.2 |
| Luna HSM version 6.3.0 with firmware 6.27.0 and Luna Client 6.3.0 |
RHEL 7.6 Windows Server 2016 Standard |
PingFedrate version 9.2 |
| Luna Cloud HSM | RHEL 7.6 Windows Server 2016 Standard |
PingFedrate version 9.2 |
Prerequisites
The prerequisites for this integration are:
Set up Luna HSM
As the first step to accomplish this integration, you need to set up either On-Premise Luna HSM or Luna Cloud HSM.
Set up On-Premise Luna HSM
Follow these steps to set up your on-premise Luna HSM:
Ensure that the HSM is set up, initialized, provisioned, and ready for deployment. For more information, refer to Luna HSM documentation.
Create a partition that will be later used by PingFederate.
Create and exchange certificate between the Luna Network HSM and client system. Register client and assign partition to create an NTLS connection.
Initialize Crypto Officer and Crypto User roles for the registered partition.
Run the following command to verify that the partition has been successfully registered and configured:
/usr/Luna/lunaclient/bin/lunacm
Upon successful execution, you should observe an output similar to the example provided below:
lunacm (64-bit) v10.3.0-275. Copyright (c) 2020 Luna. All rights reserved. Available HSMs: Slot Id -> 0 Label -> INTG_PF01 Serial Number -> 1213475834492 Model -> LunaSA 7.7.0 Firmware Version -> 7.7.0 Bootloader Version -> 1.1.2 Configuration -> Luna User Partition With SO (PW) Signing With Cloning Mode Slot Description -> Net Token Slot FM HW Status -> FM Ready
Enable partition policies 22 and 23 to allow activation and auto-activation, in case you are using PED-authenticated HSMs.
Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.
Set up Luna HSM High-Availability Group
Refer to Luna HSM documentation for HA steps and details regarding configuring and setting up two or more HSM boxes on host systems. You must enable the HAOnly setting in HA for failover to work so that if the primary goes down due to any reason, all calls get automatically routed to the secondary until the primary recovers and starts up.
Set up Luna HSM in FIPS Mode
To configure Luna HSM in FIPS Mode, update the configuration file by adding or modifying the following setting within the [Misc] section:
RSAKeyGenMechRemap=1
This setting ensures that older calling mechanisms are redirected to the approved RSA key generation methods (186-3 with primes and 186-3 with aux primes) required for FIPS compliance. By making this configuration change, Luna HSM will be properly set up to operate in FIPS mode, adhering to the approved RSA key generation standards.
The configuration setting mentioned above, RSAKeyGenMechRemap=1, is not required for the Universal Client. It is applicable only for Luna Client 7.x.
Manage User Access to the HSM
By default, access to the HSM device is limited to the root user. If you need to grant access to the HSM for specific non-root users, you can achieve this by including them in the hsmusers group. The hsmusers group is automatically generated during the client software installation process and remains intact even if you uninstall the client software. This design enables you to update your client software without losing your hsmusers group settings.
Add users to the hsmusers group
If you wish to permit non-root users or applications to interact with the HSM device, you must assign these users to the hsmusers group. Make sure that the users you intend to add to the hsmusers group are already established on the client workstation. Only users added to the hsmusers group will be granted access to the HSM device. Follow these steps to add a user to the hsmusers group:
Ensure that you possess sudo privileges on the client workstation.
Add a user to the hsmusers group using the command:
sudo gpasswd --add <username> hsmusers
Replace username with the actual username you want to include in the hsmusers group.
Remove users from the hsmusers group
If you need to withdraw a user's authorization to access the HSM device, you can remove them from the hsmusers group. Carry out the following steps to remove a user from the hsmusers group:
Confirm that you hold sudo privileges on the client workstation.
Eliminate a user from the hsmusers group using the command:
sudo gpasswd --add <username> hsmusers
Replace username with the specific username you want to exclude from the hsmusers group. To observe the changes, you will need to log in again.
Any user you remove will retain access to the HSM device until the client workstation is rebooted.
Set up Luna Cloud HSM
Follow these steps to set up your Luna Cloud HSM:
Transfer the downloaded .zip file to your client workstation using pscp, scp, or other secure means
This integration has been certified on the RHEL platform.
Extract the .zip file into a directory on your client workstation.
Extract or untar the appropriate client package for your operating system. Do not extract to a new subdirectory; place the files in the client install directory.
tar -xvf cvclient-min.tar
Run the setenv script to create a new configuration file containing information required by the Luna Cloud HSM service.
source ./setenv
To add the configuration to an already installed UC client, use the –addcloudhsm option when running the setenv script.
Run the LunaCM utility and verify that the Cloud HSM service is listed.
If your organization requires non-FIPS algorithms for your operations, ensure that the Allow non-FIPS approved algorithms check box is checked. For more information, refer to Supported Mechanisms.
Install PingFederate
PingFederate operates using J2EE application server technology. To get started with PingFederate, you can access the user documentation at https://support.pingidentity.com/s/PingFederate-help. This guide will provide step-by-step instructions for installing, licensing, and initializing the configurations necessary to smoothly integrate with Luna HSMs. Once everything is set up, you can access the PingFederate Administration Console using the URL: https://<pf_host>:9999/pingfederate/app.
For PingFederate 10.1 and earlier, the administrative console is available at https://<pf_host>:9999/pingfederate app. Here, <pf_host> refers to your PingFederate server's network address. This can be an IP address, a hostname, or a fully qualified domain name. It's essential that your computer can reach this address.
Configuring PingFederate with Luna HSM
This section describes how to integrate PingFederate with Luna HSMs. Luna HSM or Luna Cloud HSM Service integrates with PingFederate to secure the SSL certificate private key and SSO signing keys. As an example, here we are using the Java Integration Kit deployed alongside PingFederate to showcase the utilization of Luna HSM-generated keys for token signing within the SSO feature.
Generating keys and certificate for PingFederate
Configuring SSL using Luna HSM generated key
Configuring SSO with PF integration kit using Luna HSM generated key
Setting up PingFederate
To set up PingFederate:
Set the JAVA_HOME environment variable and adjust the PATH environment variable at the system level.
For Linux:
export JAVA_HOME=<java installation directory path>
export PATH=$JAVA_HOME/bin:$PATH
For Windows:
Set the JAVA_HOME environment variable and modify the PATH environment variable at the system level.
Configure Java Interface for Luna Provider.
For JDK 11:
a. Edit $JAVA_HOME/conf/security/java.security and modify the provider list:
security.provider.1=SUN
security.provider.2=SunEC
security.provider.3=SunJSSE
security.provider.4=SunJCE
security.provider.5=SunJGSS
security.provider.6=SunSASL
security.provider.7=XMLDSig
security.provider.8=SunPCSC
security.provider.9=JdkLDAP
security.provider.10=JdkSASL
security.provider.11=SunPKCS11
security.provider.12=com.safenetinc.luna.provider.LunaProvider
security.provider.13=SunRsaSign
b. Create a setenv.sh file in the <pf_install>/pingfederate/bin directory with the following variables.
!/bin/sh
export PF_CLASSPATH=/usr/safenet/lunaclient/jsp/lib/LunaProvider.jar export JAVA_OPTS=-Djava.library.path=/usr/safenet/lunaclient/jsp/lib/
c. Navigate to the /pingfederate/bin directory and configure the environment variables specified in the setenv.sh file.
. setenv.sh
When working with JDK 11 and Luna HSM configuration, ensure that the above environment variables are set each time the PingFederate service is started or restarted. Failure to do so will result in the service failing to start.
For JDK 8:
a. Open the Java Security Configuration file located at $JAVA_HOME/conf/security/java.security. In this file, incorporate the Luna Provider into the java.security file. Adjust the list of providers as follows:
security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=com.Lunainc.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
b. Copy Luna library and program files to the Java installation:
Windows
i. Move the <Luna installation directory>\jsp\lib\LunaAPI.dll file to any chosen directory and include the directory's path as a system variable. Alternatively, you have the option to place the file in the Windows system directory (C:\Windows\System32).
ii. Transfer the <Luna installation directory>\jsp\lib\LunaProvider.jar file to the JAVA_HOME\jre\lib\ext directory. Please note that both LunaProvider.jar and libLunaAPI.dll files for Luna Cloud HSM can be found in the following location:
<DPoD client directory>/LunaProvider.jar
<DPoD client directory>/libLunaAPI.dll
Linux
Transfer the libLunaAPI.so and LunaProvider.jar files from the <Luna installation directory>/jsp/lib directory to the JAVA_HOME/jre/lib/ext directory. You can locate LunaProvider.jar and libLunaAPI.so at the following location:
<DPoD client directory>/jsp/LunaProvider.jar
<DPoD client directory>/jsp/64/libLunaAPI.so
Open the hivemodule.xml file located within the <pf_install>/pingfederate/server/default/conf/META-INF directory and update the section.
a. For the JCEManager service endpoint, change the value of the construct class:
b. For the CertificateService service endpoint, change the value of the construct class:
Modify the <pf_install>/pingfederate/bin/run.properties file.
a. Change the value of the pf.hsm.mode property from OFF to LUNA.
pf.hsm.mode=LUNA
b. Change the value of the pf.hsm.hybrid property to true.
pf.hsm.hybrid=true
If you are performing a fresh PingFederate installation, set pf.hsm.hybrid property to false. When this property is set to false, any certificates that are being created or imported, such as your signing certificate or encryption key, will be stored on your HSM.
If you are configuring an existing PingFederate installation, set the pf.hsm.hybrid to true. This 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.
From the <pf_install>/pingfederate/bin directory, run the hsmpass.bat batch file for Windows, or the hsmpass.sh script for Linux. Enter the NTLS password when prompted. This procedure sets and securely stores the password for NTLS communication to the HSM from PingFederate.
Edit the com.pingidentity.crypto.LunaPartitions.xml file located in the <pf_install>/pingfederate/server/default/data/config-store directory and update the <con:config> section. For the con:item, change the value of name attribute, as explained here:
Original
<con:item name="DefaultPartitionSlotOrLabel">tokenlabel:label</con:item>
Modified
<con:item name="DefaultPartitionSlotOrLabel">slot:id</con:item>
In this context, label signifies the name assigned to the HSM partition, while id pertains to the slot ID associated with the partition.
If using an Luna Cloud HSM service, create the soft link that points to the Luna Cloud HSM configuration file in the /etc directory.
ln -sf <DPoD client directory>/Chrystoki.conf /etc/Chrystoki.conf
This concludes the set up process for PingFederate. You are required start or restart the PingFederate server for the changes to take effect.
Managing Keys and Certificates for PingFederate
Adhere to the following guidelines to manage keys and certificates on the Luna HSMs through the PingFederate administrative console.
Managing SSL server certificates
To manage the certificates for accessing the PingFederate admin console and handling incoming HTTPS connections:
Access the PingFederate administrative console.
Click Security from the left side navigation pane.
Choose SSL Server Certificates from the options displayed.
Execute one of the following procedures, depending on your requirements:
Create a new certificate
To create a new certificate:
On the SSL Server Certificates screen, click Create new.
On the Create Certificate screen, enter the required information. For information about each field, refer to the following table:
| Field | Description |
|---|---|
| Common Name | The common name (CN) identifying the certificate. |
| Subject Alternative Names | The additional DNS names or IP addresses that can be associated with the certificate. |
| Organization | The organization (O) or company name creating the certificate. |
| Organizational Unit | The specific unit within the organization (OU). |
| City | The city or other primary location (L) where the company operates. |
| State | The state (ST) or other political unit encompassing the location. |
| Country | The country (C) where the company is based. |
| Validity (days) | The time during which the certificate is valid. |
| Cryptographic Provider | The storage facility of the certificate. Select HSM to store the certificate in the HSM. |
| Key Algorithm | A cryptographic formula used to generate a key. PingFederate uses either of two algorithms, RSA or EC. |
| Key Size (bits) | The number of bits used in the key. |
| Signature Algorithm | The signing algorithm of the certificate. |
When finished, click Next.
Ensure that check boxes Make this an active certificate for the Runtime Server and Make this an active certificate for the Admin Console are selected. Click Done.
On the Summary screen, review your configuration, amend as needed, and click Save.
Create a certificate authority signing request
To create a certificate authority signing request (CSR):
On the SSL Server Certificates screen, select Certificate Signing under Action.
This selection is inactive if you have not yet saved a newly created or imported certificate. Click Save and then return to this screen to initiate the process.
On the Certificate Signing screen, select the Generate CSR option.
On the Generate CSR screen, click Export to store the CSR file, and then click Done.
Once the CSR file is saved, you can sent it to a certificate authority (CA) to obtain a CA-signed certificate.
Import a certificate authority response (CSR response)
On the SSL Server Certificates screen, select Certificate Signing under Action.
On the Certificate Signing screen, select the Import CSR Response option.
On the Import CSR Response screen, choose the applicable CSR response file.
On the Summary screen, review your configuration, click Save to keep your configuration or click Cancel to discard it.
Import a certificate and its private key
On the SSL Server Certificates screen, click Import.
On the Import Certificate screen, choose the applicable certificate file and enter its password.
Select HSM to store the certificate in the HSM.
On the Summary screen, review your configuration and amend as needed.
Click Save to keep your configuration, or click Cancel to discard it.
Managing SSL client keys and certificates
To manage your authentication private keys and the certificates your server uses as a client in outbound SSL/TLS transactions, follow these steps:
Access the PingFederate administrative console.
Click Security from the left side navigation pane.
Choose SSL Client Keys & Certificates from the options displayed.
Execute one of the following procedures, depending on your requirements:
Managing digital signing certificates and decryption keys
To efficiently manage certificates with a wide range of applications, including signing outgoing requests, responses, assertions, access tokens, and decryption needs:
Access the PingFederate administrative console.
Click Security from the left side navigation pane.
Choose Signing & Decryption Keys & Certificates from the options displayed.
Execute one of the following procedures, depending on your requirements:
Configuring SSL using Luna HSM generated key
From the PingFederate administrative console, click Security > SSL Server Certificates screen to configure the SSL certificate for PingFederate server. To configure SSL using Luna HSM generated key:
On the SSL Server Certificates screen, under Action for the HSM generated certificate, select Activate Default for Admin Console.
On the SSL Server Certificates screen, under Action for the HSM generated certificate, select Activate Default for Runtime Server.
Click Save.
Open the administrative console again and verify that the default SSL certificate is replaced with HSM generated certificate for SSL.
Configuring SSO with PF integration kit using Luna HSM generated key
The PF Integration Kit distribution contains sample IdP and SP applications. The applications facilitate swift testing of OpenToken processing and provide a functional demonstration of end-to-end single sign-on (SSO) and single logout (SLO). The PF Integration Kit can be downloaded from the Ping Identity Add-ons resource page. We have tested the following PF integration kits:
-
Agentless Integration Kit
-
Java Integration Kit
Before configuring Luna HSM or Luna Cloud HSM with PingFederate, ensure that the Sample Apps provided in the Integration Kit are properly installed and configured.
Refer to the PingFederate integration kit documentation to install and configure the PF integration kit Sample App for both IdP and SP.
Sample App provided by integration kits can be used for demonstration and testing only.
After installation, verify the successful deployment of your Sample App. To use the signing key generated on Luna HSM for SSO and Sample App Token signing, perform the steps explained here:
Verify the SSO feature provided by integration kit using Luna HSMs
To verify the SSO feature provided by integration kit using Luna HSMs:
Log in to the PingFederate Administrative Console.
Click Security > Signing & Decryption Keys & Certificates.
Under Action, click Export.
Click Next, and then click Export to export the certificate.
Click Save File when prompted, and then click Done.
Click Identity Provider.
Under Idp Connections, click the SAML2.0 entity.
On Idp Connection page, click Credentials > Configure Credentials > Digital Signature Settings.
Select the Signing Certificate generated on the Luna HSM and Signing Algorithm. Click Next.
Click Manage Signature Verification Settings > Signature Verification Certificates > Manage Certificates > Import.
Import the certificate. Click Choose File and select the certificate exported from HSM in step 4. Click Next.
Ensure that the Make this an active verification certificate check box is selected. Click Done.
Click Done to confirm the certificate. Click Save.
Click Service Provider.
Under Sp Connections, click the SAML2.0 entity.
On Sp Connection Page, Click Credentials > Configure Credentials > Digital Signature Settings.
Select the Signing Certificate generated on Luna HSM and the Signing Algorithm. Click Next.
Click Manage Signature Verification Settings > Signature Verification Certificates > Manage Certificates > Import.
To import certificate, click Choose File and select the certificate exported from HSM in step 4. Click Next.
Ensure that Make this an active verification certificate check box is selected. Click Done.
Click Done to confirm the certificate. Click Save.
Restart the PingFederate service for changes to take effect.
Open the browser and access the IdP Sample application URL: https://localhost:9031/IdpSample
Click on Local Login. Enter credentials (joe/test) and click Login. After logging in, you will be able to see the user attributes for Idp Application.
Click on Single Sign-On and you will be automatically logged in SP application without any credential using SSO.
This validates the operational integrity of the PingFederate SSO feature, ensuring that each token generated by the application is duly signed by the secure signing and decryption key safeguarded within the Luna HSM.
