How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure AM 6.x to use a Hardware Security Module (HSM) for signing SAML assertions?

Last updated Jan 12, 2023

The purpose of this article is to provide information on configuring AM to use a Hardware Security Module (HSM) for signing SAML assertions, where the SAML keys are stored in a PKCS11 keystore. AM uses a JCEKS or JKS keystore by default (depending on AM version). It should be noted that HSM protection applies to signing keys only. Symmetric keys used for SAML2 encryption are not generated or stored on the HSM.

2 readers recommend this article
Note

This article does not apply to AM 7 and later, because SAML signing and encryption uses AM's secret stores functionality as of AM 7. See Mapping and Rotating Secrets for further information on managing these secrets.

AM supports the PKCS#11 standard interface and you may choose to use your own HSM implementation of this interface. However, when diagnosing issues, ForgeRock may request that a standard provider is used to eliminate HSM-specific issues from the equation.

Prerequisites

  1. Install the PKCS11 provider in the Java® Security properties file ($JAVA_HOME/lib/security/java.security) by specifying the sun.security.pkcs11.SunPKCS11 class. For example: security.provider.10=sun.security.pkcs11.SunPKCS11 /opt/bar/cfg/pkcs11.cfgwhere pkcs11.cfg contains the appropriate configuration for your HSM's PKCS#11 implementation.
  2. Confirm this is working by listing the keystore contents using the following command: $ keytool -keystore NONE -storetype PKCS11 -list

See Java PKCS#11 Reference Guide - Configuration and Java PKCS#11 Reference Guide - KeyTool and JarSigner for further information.

Configuring AM

This example process assumes that a private key and certificate alias called mykey already exists in the PKCS11 keystore; however, it is possible that several different aliases could be used in your setup and you will need to adjust this process as necessary.

  1. Update the keystore details using either the AM admin UI or ssoadm:
    • AM admin UI: navigate to: Configure > Server Defaults > Security > Key Store and update the following details:
      • Keystore File - enter the following, where dummy.jks must be a 0 bytes file: %BASE_DIR%/%SERVER_URI%/dummy.jks
      • Keystore Type - enter PKCS11.
      • Keystore Password File - enter the following to specify the path to the password file for the keystore, where the password contained in this file is in cleartext (the password can be encrypted using encode.jsp or ampassword before being stored in cleartext). %BASE_DIR%/%SERVER_URI%/.pass
      • Private Key Password File - enter the following to specify the path to the password file for the private key aliases contained in the keystore, where the password contained in this file is in cleartext (the password can be encrypted using encode.jsp or ampassword before being stored in cleartext). If the key alias password matches the key store password, you can just set this field the same as above. %BASE_DIR%/%SERVER_URI%/.privatepass
    • ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.sun.identity.saml.xmlsig.keystore=%BASE_DIR%/%SERVER_URI%/dummy.jks com.sun.identity.saml.xmlsig.storetype=PKCS11 com.sun.identity.saml.xmlsig.storepass=%BASE_DIR%/%SERVER_URI%/.pass com.sun.identity.saml.xmlsig.keypass=%BASE_DIR%/%SERVER_URI%/.privatepassreplacing [adminID] and [passwordfile] with appropriate values.
  2. Create the 0 byte dummy.jks file and the password file(s) that you referenced in step 1.
  3. Update the metadata signing key alias (mykey in this example) using either the AM admin UI or ssoadm:
    • AM admin UI: navigate to: Configure > Global Services > SAMLv2 Service Configuration > Realm Defaults > Metadata signing key alias and update it to: mykey. You can leave the Metadata signing key password unchanged.
    • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s sunFAMSAML2Configuration -t organization -u [adminID] -f [passwordfile] -a metadataSigningKey=mykeyreplacing [adminID] and [passwordfile] with appropriate values.
  4. Update the certificate alias (mykey in this example) in the top level realm using either the AM admin UI or ssoadm:
    • AM admin UI: navigate to: Realms > Top Level Realm / > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias and update it to: mykey.
    • ssoadm: enter the following command: $ ./ssoadm set-realm-svc-attrs -s iPlanetAMAuthService -e / -u [adminID] -f [passwordfile] -a iplanet-am-auth-key-alias=mykeyreplacing [adminID] and [passwordfile] with appropriate values.
  5. Create your hosted IdP or SP if you haven't already done so.
  6. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and select the hosted IdP or SP.
  7. Navigate to Assertion Content > Signing and Encryption > Certificate Aliases > Signing and enter: mykey. Leave the Key Pass field blank to use the password stored in %BASE_DIR%/%SERVER_URI%/.pass.
  8. Confirm that the metadata is signed using the expected key and certificate via the REST API using a command similar to the following: $ curl https://am.example.com:8443/am/saml2/jsp/exportmetadata.jsp?sign=true

See Also

How do I create persistent SAML federation between two AM servers (All versions) where user attributes match?

Changing Default Key Aliases

SAML v2.0 Guide​

Java PKCS#11 Reference Guide - Configuration

Java PKCS#11 Reference Guide - KeyTool and JarSigner

Related Training

N/A

Related Issue Tracker IDs

OPENAM-11249 (Ability to store all keys and secrets in a HSM)

Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.