PingAM

Configure Luna HSM

Set up pingAM

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 on used by PingAM.

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/safenet/lunaclient/bin/lunacm

Upon successful execution, you should observe an output similar to the example provided below:

lunacm (64-bit) v10.7.2-16. Copyright (c) 2024 Thales Group. All rights reserved.
Available HSMs:

Slot Id ->                           0
Label ->                             TPA01
Serial Number ->                     1312109862218
Model ->                             LunaSA 7.7.1
Firmware Version ->                  7.7.1
Bootloader Version ->                1.1.2
Configuration ->                     Luna User Partition With SO (PW) Key Export With Cloning Mode
Slot Description ->                  Net Token Slot
FM HW Status ->                      Non-FM   
Current Slot Id ->                   0

Refer to Luna HSM documentation for detailed steps on creating NTLS connection, initializing the partitions, and assigning various user roles.

For proper configuration of a PED-based Luna HSM, it is recommended to activate partition policies 22 and 23, allowing for both activation and auto-activation.

This integration is fully tested with both HA and FIPS modes.

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.

Confirm that you hold sudo privileges on the client workstation.

Eliminate a user from the hsmusers group using the command:

sudo gpasswd --delete <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.

Understand the OpenAM Platform: Refer to the PingAM documentation for installation, pre-installation requirements, and deployment options.

Install PingAM: Set up PingAM on the target machine following the recommended guidelines.

Verify the Installation: Ensure that PingAM is running and accessible before proceeding with integration.

Set environment variables to ensure the web server runs with the correct configuration:

export CATALINA_BASE=/opt/apache-tomcat   # If using Apache Tomcat  
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-11.0.25.0.9-2.el8.x86_64  
export PATH=$JAVA_HOME/bin:$PATH  

These variables must be set on all PingAM instances.

Create your own key aliases in the PKCS11 keystore and update the default key aliases in the Admin UI and Secret ID mappings to match your setup. AM generates demo keys in a JCEKS keystore located at /path/to/openam/security/keystores.

This demonstration uses the same key aliases as those stored in the JCEKS keystore. If using different key aliases, refer to the PingAM documentation for modifying default key aliases and mapping and rotating secrets.

List default key aliases in the JCEKS keystore to identify the keys stored by PingAM. Navigate to the keystore directory and run the following command:

cd /root/openam/security/keystores/
keytool -list -keystore keystore.jceks -storetype jceks -storepass:file ../secrets/default/.storepass -keypass:file ../secrets/default/.keypass

This command lists key aliases along with their key types:

es256test (ECDSA key)
es384test (ECDSA key)
es512test (ECDSA key)
hmacsigningtest (Symmetric HMAC key)
directenctest (Symmetric Direct AES encryption key)
rsajwtsigningkey (Asymmetric RSA key)
selfserviceenctest (Asymmetric RSA key)
selfservicesigntest (Symmetric secret signing key)
test (Asymmetric RSA key)
*configstorepwd (password string)
*dsameuserpwd (password string)

The configstorepwd and dsameuserpwd aliases are created during AM restart. These store configuration passwords used during startup.

This guide demonstrates using the same key aliases for keys generated on Luna HSM as those in the JCEKS keystore. If different aliases are used, follow the PingAM documentation on modifying default key aliases and mapping and rotating secrets.

Create a PKCS11 configuration file (luna.cfg) in a writable directory, such as /opt, to define how the Luna HSM is accessed.

vi /opt/luna.cfg

Add the following content:

# SafeNet Luna HSM Configuration

name = Luna
library = /usr/safenet/lunaclient/lib/libCryptoki2_64.so
description = Luna config
slot = 0

attributes(*,*,*) = {
    CKA_TOKEN = true
}

attributes(*,CKO_SECRET_KEY,*) = {
    CKA_CLASS = 4
    CKA_LABEL = true
    CKA_PRIVATE = true
    CKA_SENSITIVE = true
    CKA_SIGN = true
    CKA_VERIFY = true
    CKA_ENCRYPT = true
    CKA_DECRYPT = true
    CKA_WRAP = true
    CKA_UNWRAP = true
}

attributes(*,CKO_PRIVATE_KEY,*) = {
    CKA_CLASS = 3
    CKA_LABEL = true
    CKA_PRIVATE = true
    CKA_SENSITIVE = true
    CKA_DECRYPT = true
    CKA_SIGN = true
    CKA_UNWRAP = true
}

attributes(*,CKO_PUBLIC_KEY,*) = {
    CKA_CLASS = 2
    CKA_TOKEN = false
    CKA_LABEL = true
    CKA_ENCRYPT = true
    CKA_VERIFY = true
    CKA_WRAP = true
}

attributes(*,CKO_PRIVATE_KEY,CKK_EC) = {
    CKA_DERIVE = true
}

This configuration must be created on all PingAM instances.

Run the following keytool command with the PKCS11 provider to generate an elliptic curve (EC) key pair on the Luna HSM, stored with the alias es256test:

keytool -genkeypair -alias es256test -keyalg EC -groupname secp256r1 -sigalg SHA256withECDSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

• Perform key generation only on one AM instance if all instances share the same Luna HSM partition.
  
• Replace userpin1 with the CO Password for Luna HSM.
  
• The command generates a certificate and private key but does not assign a label to the private key.
  

List the key handles to identify the newly generated private key.

/usr/safenet/lunaclient/bin/cmu list -password userpin1

Example output:

handle=1421     label=es256test
handle=1429     label=

Assign the missing key label.

/usr/safenet/lunaclient/bin/cmu setattribute -password userpin1 -handle=1429 -label=es256test

Verify that the private key and certificate labels match.

/usr/safenet/lunaclient/bin/cmu list -password userpin1

Expected output:

handle=1421     label=es256test
handle=1429     label=es256test

Repeat this process for all asymmetric key aliases using the appropriate key generation commands:

keytool -genkeypair -alias es384test -keyalg EC -groupname secp384r1 -sigalg SHA384withECDSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genkeypair -alias es512test -keyalg EC -groupname secp521r1 -sigalg SHA512withECDSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genseckey -alias hmacsigningtest -keyalg HmacSHA256 -keysize 256 -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genseckey -alias directenctest -keyalg AES -keysize 256 -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genkeypair -alias rsajwtsigningkey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genkeypair -alias selfserviceenctest -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genseckey -alias selfservicesigntest -keyalg HmacSHA256 -keysize 256 -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

keytool -genkeypair -alias test -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

When generating asymmetric keys with the keytool command, a self-signed certificate is created by default. If a CA-signed certificate is required, generate a certificate signing request, submit it to a CA for signing, and then import the CA-signed certificate into the PKCS11 keystore. If using a self-signed certificate, skip steps 10-11, as they are only required for CA-signed certificates.

Generate a certificate request for an asymmetric key in the keystore.

keytool -certreq -alias test -sigalg SHA256withRSA -file certreq_file -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg

Submit the certificate signing request (CSR) to a CA. Once signed, the CA will return a certificate or a certificate chain.

Import the signed certificate reply into the PKCS11 keystore.

keytool -importcert -trustcacerts -alias test -file certchain.p7b -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /root/openam/security/keystores/luna.cfg

Update java.security to configure SunPKCS11 as a provider.

Open 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=SunPKCS11 /opt/luna.cfg
security.provider.6=SunJGSS
security.provider.7=SunSASL
security.provider.8=XMLDSig
security.provider.9=SunPCSC
security.provider.10=JdkLDAP
security.provider.11=JdkSASL
security.provider.12=com.safenetinc.luna.provider.LunaProvider
security.provider.13=SunRsaSign

This step must be performed on all AM instances.

Verify the generated key materials on the Luna HSM using PKCS11 provider.

keytool -list -keystore NONE -storetype PKCS11 -storepass userpin1 -providerClass sun.security.pkcs11.SunPKCS11 -providerArg /opt/luna.cfg -providerName SunPKCS11-Luna

This command lists all keys and certificates stored in the Luna HSM partition.

Ensure AM is running and that the AM admin UI is accessible with administrative credentials.

Navigate to a writable directory that is shared across all AM instances and create an empty PKCS11 keystore file.

cd /root/openam/security/keystores/
touch PKCS11

Store the PKCS11 keystore password in cleartext in a writable secrets directory.

cd /root/openam/security/secrets/default/
echo -n co_password > .hsmpass

Replace co_password with the actual password.

Set read-only permissions for the password file to restrict access.

chmod 400 .hsmpass

Navigate to the encrypted secrets directory shared across all AM instances.

cd /root/openam/security/secrets/encrypted

Open the AM encoding page in a web browser:

https://authz.example.com:8443/openam/encode.jsp

Enter the Crypto Officer (CO) password and copy the encoded password.

Store the encoded password in a file named hsmpass and set the correct permissions.

echo -n "encoded_password" > hsmpass
chmod 400 hsmpass

Replace "encoded_password" with the actual encoded value.

Log in to the AM admin UI, go to Configure > Server Defaults > Security > Key Store, and enter the keystore file name and path in the Keystore File field.

%BASE_DIR%/security/keystores/PKCS11

%BASE_DIR% represents the AM installation base directory. Ensure the keystore path is correct for your setup.

Set Keystore Type to PKCS11.

Enter the keystore password file path in the Keystore Password File field.

%BASE_DIR%/security/secrets/default/.hsmpass

Enter the private key password file path in the Private Key Password File field.

%BASE_DIR%/security/secrets/default/.hsmpass

In the Certificate Alias field, enter the key alias generated on Luna HSM. The alias must match the one configured in Realms > [Realm Name] > Authentication > Settings > Security as the Persistent Cookie Encryption Certificate Alias.

Example:

test

Click Save Changes.

AM still retains the previous keystore configuration in memory and cannot yet use key aliases from the new keystore. Ensure the keystore files are available in the same location across all AM instances. This may involve mounting a shared filesystem or copying files manually.

Restart all AM instances to apply the new keystore settings. The updated keystore and its keys are now in effect.

Log in to the AM admin UI as an administrative user and create a secret store.

• To create a global secret store, navigate to Configure > Secret Stores.

• To create a realm-specific secret store, go to Realms > [Realm Name] > Secret Stores.

Click Add Secret Store.

Enter a unique Secret Store ID (e.g., pkcs11-keystore).

From the Store Type drop-down list, select Keystore.

Enter the keystore file name in the File field.

/root/openam/security/keystores/PKCS11

Ensure this file is accessible to all AM instances by storing it on a shared filesystem or manually copying and maintaining it across instances.

Click Create.

Set Keystore Type to PKCS11.

Enter SunPKCS11-Luna in the Provider Name field.

Enter hsmpass in the Store Password Secret ID field.

Enter hsmpass in the Entry Password Secret ID field.

Set the Key Lease Expiry Time (in minutes) as required.

Click Save Changes.

Navigate to Configure > Secret Stores > default-keystore > Mappings tab.

Copy all Secret IDs and Aliases and save them in a text file for reference.

Delete all keys and secret mappings from the Mappings tab of default-keystore.

Add the same Secret IDs and Aliases that were deleted from default-keystore to the Mappings tab of pkcs11-keystore. Use the text file saved earlier as a reference.

In the AM admin UI, navigate to the realm, select Secret Stores, and add a new keystore named pkcs11-keystore.

Provide the same details as configured for the global pkcs11-keystore. Click Save Changes.

Add the realm-level Secret IDs and Aliases to the Mappings tab of pkcs11-keystore. Use the text file saved earlier as a reference.

Repeat these steps for all realms in the environment to create pkcs11-keystore and configure the necessary mappings.

Navigate to the keystore directory, create a backup of the existing JCEKS keystore, and then delete all key aliases that were migrated to the PKCS11 keystore.

# cd /root/openam/security/keystores/
# cp keystore.jceks keystore.jceks.b4.hsm 

Delete the migrated key aliases one by one:

# keytool -delete -alias test -keystore keystore.jceks -storetype jceks -storepass:file ../secrets/default/.storepass -keypass:file ../secrets/default/.keypass

Repeat the keytool -delete command for all aliases:

• es256test (ECDSA key)

• es384test (ECDSA key)

• es512test (ECDSA key)

• hmacsigningtest (Symmetric HMAC key)

• directenctest (Symmetric Direct AES encryption key)

• rsajwtsigningkey (Asymmetric RSA key)

• selfserviceenctest (Asymmetric RSA key)

• selfservicesigntest (Symmetric secret signing key)

• test (Asymmetric RSA key)

Ensure all aliases listed above are deleted from the JCEKS keystore.

Follow the steps provided in the AM OAuth 2.0 documentation for protecting a website with OAuth 2.0. This includes setting up the Authorization Server, Client, and Resource Server and installing the Java Agent.

Replace the AM server and Resource Server URLs in the configuration with the URLs specific to your environment.

Map the key aliases generated on Luna HSM in the Secret Store mappings, as previously done for the default key aliases.

Configure AM Secret IDs for the OAuth 2.0 provider to use the correct key aliases:

• Sign JWTs using the secret mapped to am.global.services.oauth2.oidc.agent.idtoken.signing. This secret ID must map to the rsajwtsigningkey key alias in the PKCS11 keystore.

• Sign claims using the secret mapped to am.services.oauth2.jwt.authenticity.signing. This secret ID must map to the hmacsigningtest key alias in the PKCS11 keystore.

Enable client-side token signing and encryption by configuring the OAuth 2.0 Provider and client. Ensure that a supported algorithm is configured. Refer to the AM documentation: Configure AM for client-side OAuth 2.0 tokens.

Review the AM documentation for details on how AM features utilize keys from the Key Store and Secret Store.

If the setup is correct, log out of any active session by opening the following URL in a web browser:

https://client.example.com:8443/openam/XUI/?realm=/#logout

After logging out, access a resource protected by the AM Java Agent to verify that authentication is enforced. You should be prompted to authenticate before gaining access.

Access the resource protected by the Java Agent by browsing the following URL. The AM Client and Authorization Server will use OAuth 2.0 tokens signed by keys stored in Luna HSM:

https://www.example.com:8443/examples/

Authenticate and approve the authorization decision by clicking Allow.

The authorization service creates an SSO session by exchanging the signed token and redirects the client back to the protected resource.

Retrieve the signed token by executing the following cURL command:

curl --request POST --user "myClientID:password" \
--data "grant_type=password&username=demo&password=Ch4ng31t&scope=cn" \
https://authz.example.com:8443/openam/oauth2/access_token

The response will contain an access token in JSON format:

"access_token":"eyJ0eXAiOiJKV1QiLCJraWQiOiI1bFJGeEY2OWt4VmxWblJlQi9zVGVuaW82dW89IiwiYWxnIjoiUlMyNTYifQ..."

Retrieve and verify the token details using the access token obtained in the previous step. This can be done by executing the following cURL command or by accessing the URL in a web browser:

curl https://authz.example.com:8443/openam/oauth2/realms/root/tokeninfo?access_token=eyJ0eXAiO......e1ItSxlbw

A successful response confirms that the OAuth 2.0 configuration is correctly set up and that the token is valid.