Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 7. Installing an IdM deployment with keys and certificates stored on an HSM

Install an Identity Management (IdM) deployment that stores core keys and certificates on a Hardware Security Module (HSM). By storing your key pairs and certificates for your IdM Certificate Authority (CA) and Key Recovery Authority (KRA) on an HSM, you add a physical security to the private key material.

An HSM provides a hardened, tamper-resistant environment for secure cryptographic processing, key generation, and encryption. IdM relies on the networking features of the HSM to share the keys between machines to create replicas. The HSM provides additional security without visibly affecting most IdM operations. When you use low-level tooling, the system handles certificates and keys differently, but this is seamless for most users.

Important

Note the following:

  • The HSM must be connected to a network.
  • The private keys cannot leave the device.
  • You cannot mix what is stored on an HSM. For example, you cannot install the KRA private keys on an HSM without also installing the CA private keys on it.
  • If you use an HSM on the initial installation, then all replicas and KRAs must also use the same HSM.
  • You cannot upgrade an existing installation where the keys were not generated on an HSM to an HSM-based install.

Using an HSM is largely invisible to users and administrators beyond passing additional options during the installation. The options required and any pre-installation work are HSM-specific.

7.1. Supported hardware security modules
Copy link

Using hardware security modules (HSMs) provides dedicated cryptographic processing for Identity Management servers. The system supports specific firmware and client software versions for devices like nCipher nShield and Thales Luna to ensure secure key management.

Expand
HSMFirmwareAppliance SoftwareClient Software

nCipher nShield Connect XC (High)

nShield_HSM_Firmware-12.72.1

12.71.0

SecWorld_Lin64-12.71.0

Thales TCT Luna Network HSM Luna-T7

lunafw_update-7.11.1-4

7.11.0-25

610-500244-001_LunaClient-7.11.1-5

Install an Identity Management (IdM) server with integrated certificate authority (CA) using HSM-stored keys to ensure hardware-backed cryptographic operations and enhanced security.

During the installation, you must supply basic configuration of the system, for example the realm, the administrator’s password and the Directory Manager’s password.

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Prerequisites

  • A supported networked HSM installed set up according to its vendors instructions. See Supported HSMs.
  • The HSM PKCS #11 library path, /opt/nfast/toolkits/pkcs11/libcknfast.so.
  • An available slot, token, and the token password.

Procedure

  1. Run the install command, ensuring you specify the location of the PKCS #11 library, the token name, and the token password: 

    ipa-server-install -a <password> -p <dmpassword>-r <IDM.EXAMPLE.COM> -U --setup-dns --allow-zone-overlap --no-forwarders -N --auto-reverse --random-serial-numbers -–token-name=<HSM-TOKEN> --token-library-path=/opt/nfast/toolkits/pkcs11/libcknfast.so
    Copy to Clipboard Toggle word wrap
  2. Specify the token password when prompted.

Verification

  1. Run certutil to display CA certificate information: 

    certutil -L -d /etc/pki/pki-tomcat/alias

Certificate Nickname                    Trust Attributes
                                        SSL,S/MIME,JAR/XPI

caSigningCert cert-pki-ca               CT,C,C
ocspSigningCert cert-pki-ca             ,,
Server-Cert cert-pki-ca                 u,u,u
subsystemCert cert-pki-ca               ,,
auditSigningCert cert-pki-ca            ,,P
    Copy to Clipboard Toggle word wrap

    Note that where there is no u listed under Trust Attributes for a certificate, it indicates the private keys are stored on the token. In this case, only the Server-Cert cert-pki-ca has the u flags as it is not installed on the HSM for performance reasons.

  2. Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias -h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard Toggle word wrap

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Install an Identity Management (IdM) server using external certificate authorities (CA) with HSM-stored keys to integrate with existing PKI infrastructure while ensuring hardware-backed security.

During the installation, you must supply basic configuration of the system, for example the realm, the administrator’s password and the Directory Manager’s password.

The ipa-server-install installation script creates a log file at /var/log/ipaserver-install.log. If the installation fails, the log can help you identify the problem.

Prerequisites

  • A supported networked HSM installed set up according to its vendors instructions. See Supported HSMs.
  • The HSM PKCS #11 library path, /opt/nfast/toolkits/pkcs11/libcknfast.so.
  • An available slot, token, and the token password.

  • If you install a server without an integrated IdM CA, you must request the following certificates from a third-party authority:

    • An LDAP server certificate
    • An Apache server certificate
    • A PKINIT certificate
    • Full CA certificate chain of the CA that issued the LDAP and Apache server certificates

Procedure

  1. Run the install command, ensuring you specify that you are using an external CA. 

    # ipa-server-install --external-ca
    Copy to Clipboard Toggle word wrap

    During the installation process, the utility prints the location of the certificate signing request (CSR) /root/ipa.csr: 

    ...

Configuring certificate server (pki-tomcatd): Estimated time 3 minutes 30 seconds
  [1/8]: creating certificate server user
  [2/8]: configuring certificate server instance
The next step is to get /root/ipa.csr signed by your CA and re-run /sbin/ipa-server-install as:
/sbin/ipa-server-install --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
    Copy to Clipboard Toggle word wrap

  2. To complete the certificate process, using the CSR generated by the installation utility, complete the following steps:

    1. Submit the CSR located in /root/ipa.csr to the external CA. The process differs depending on the service to be used as the external CA.

    2. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob (either a PEM file or a Base_64 certificate from a Windows CA). Again, the process differs for every certificate service. Usually, a download link on a web page or in the notification email allows the administrator to download all the required certificates.

      Important

      Obtain the full certificate chain for the CA, not just the CA certificate.

  3. Run the ipa-server-install utility again to specify the path and names of the newly-issued CA certificate and the CA chain files and the location of the PKCS #11 library, the token name, and the token password: 

    # ipa-server-install --external-cert-file=</tmp/servercert20170601.pem> --external-cert-file=</tmp/cacert.pem> -–token-name=<HSM-TOKEN> --token-library-path=/opt/nfast/toolkits/pkcs11/libcknfast.so
    Copy to Clipboard Toggle word wrap
  4. Specify the token password when prompted.
  5. The installation script now configures the server. Wait for the operation to complete.

Verification

  1. Run certutil to display CA certificate information: 

    certutil -L -d /etc/pki/pki-tomcat/alias

Certificate Nickname                    Trust Attributes
                                        SSL,S/MIME,JAR/XPI

caSigningCert cert-pki-ca               CT,C,C
ocspSigningCert cert-pki-ca             ,,
Server-Cert cert-pki-ca                 u,u,u
subsystemCert cert-pki-ca               ,,
auditSigningCert cert-pki-ca            ,,P
    Copy to Clipboard Toggle word wrap

    You can see the certificates but the ,, indicates no private keys as they are stored on the token.

  2. Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>

Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard Toggle word wrap

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Install Identity Management (IdM) replicas with HSM-stored keys and certificates to enhance security and ensure hardware-backed cryptographic operations across the infrastructure.

The replica installation process copies the configuration of the existing server and installs the replica based on that configuration.

Prerequisites

Procedure

  1. Run the install command, ensuring you specify the token name: 

    # ipa-replica-install --token-name=<HSM-TOKEN> --setup-ca -P admin -w <password> -U
    Copy to Clipboard Toggle word wrap
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>
    Copy to Clipboard Toggle word wrap 
    Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
    Copy to Clipboard Toggle word wrap

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Install Key Recovery Authority (KRA) on Identity Management (IdM) servers with HSM-stored keys to enable secure vault functionality and protect sensitive credentials.

Prerequisites

  • The token password.

Procedure

  1. Run the install command, ensuring you specify the token name and the token password: 

    # ipa-kra-install -p <password>
    Copy to Clipboard Toggle word wrap
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>
    Copy to Clipboard Toggle word wrap 
    Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
<HSM-TOKEN>:storageCert cert-pki-kra                           u,u,u
<HSM-TOKEN>:transportCert cert-pki-kra                         u,u,u
<HSM-TOKEN>:auditSigningCert cert-pki-kra                      u,u,Pu
    Copy to Clipboard Toggle word wrap

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Install Key Recovery Authority (KRA) clones on Identity Management (IdM) replicas with HSM-stored keys to enable secure vault services and distributed key recovery.

By default an IdM replica does not have a KRA, unless you specified the --setup-kra option during the IdM client promotion.

Prerequisites

  • The token password.
  • A KRA server installed.

Procedure

  1. To install a KRA clone, execute the following command on the replica: 

    # ipa-kra-install -p <Secret.123 >
    Copy to Clipboard Toggle word wrap
  2. Specify the token password when prompted.

Verification

  • Verify that the keys and certificates are stored on the HSM: 

    certutil -L -d /etc/pki/pki-tomcat/alias - h <HSM-TOKEN>
    Copy to Clipboard Toggle word wrap 
    Certificate Nickname                                Trust Attributes
	   SSL,S/MIME,JAR/XPI

Enter Password or Pin for "<HSM-TOKEN>":
<HSM-TOKEN>:subsystemCert cert-pki-ca                  	u,u,u
<HSM-TOKEN>:ocspSigningCert cert-pki-ca                	u,u,u
<HSM-TOKEN>:caSigningCert cert-pki-ca                  	CTu,Cu,Cu
<HSM-TOKEN>:auditSigningCert cert-pki-ca               	u,u,Pu
<HSM-TOKEN>:storageCert cert-pki-kra                           u,u,u
<HSM-TOKEN>:transportCert cert-pki-kra                         u,u,u
<HSM-TOKEN>:auditSigningCert cert-pki-kra                      u,u,Pu
    Copy to Clipboard Toggle word wrap

    The certificate name is prefixed with the HSM token name, which indicates that the private keys and certificates are stored on the token.

    Where the keys are stored does not affect how users obtain or use certificates.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top