Chapter 44. Using IdM CA renewal master

44.1. Explanation of IdM CA renewal master

In an Identity Management (IdM) deployment that uses an embedded certificate authority (CA), the CA renewal master server maintains and renews IdM system certificates. It ensures nondisruptive IdM deployments.

IdM system certificates include:

  • IdM CA certificate
  • OCSP signing certificate
  • IdM CA subsystem certificates
  • IdM CA audit signing certificate
  • IdM renewal agent (RA) certificate
  • KRA transport and storage certificates

What characterizes system certificates is that their keys are shared by all CA replicas. In contrast, the IdM service certificates (for example, LDAP, HTTP and PKINIT certificates), have different keypairs and subject names on different IdM CA servers.

In IdM topology, by default, the first master IdM CA server is the CA renewal master.

Note

In upstream documentation, the IdM CA is called Dogtag.

The role of the CA renewal master server

The IdM CA, IdM CA subsystem, and IdM RA certificates are crucial for IdM deployment. Each certificate is stored in an NSS database in the /etc/pki/pki-tomcat/ directory and also as an LDAP database entry. The certificate stored in LDAP must match the certificate stored in the NSS database. If they do not match, authentication failures occur between the IdM framework and IdM CA, and between IdM CA and LDAP.

All IdM CA replicas have tracking requests for every system certificate. If an IdM deployment with integrated CA does not contain a CA renewal master, each IdM CA server requests the renewal of system certificates independently. This results in different CA replicas having various system certificates and authentication failures occurring.

Appointing one CA replica as the renewal master allows the system certificates to be renewed exactly once, when required, and thus prevents authentication failures.

The role of certmonger on CA replicas

The certmonger service running on all IdM CA replicas uses the dogtag-ipa-ca-renew-agent renewal helper to keep track of IdM system certificates. The renewal helper program reads the CA renewal master configuration. On each CA replica that is not the CA renewal master, the renewal helper programme retrieves the latest system certificates from the ca_renewal LDAP entries. Due to non-determinism in when exactly certmonger renewal attempts occur, the dogtag-ipa-ca-renew-agent helper sometimes attempts to update a system certificate before the CA renewal master has actually renewed the certificate. If this happens, the old, soon-to-expire certificate is returned to the certmonger on the CA replica. The certmonger, realizing it is the same certificate that is already stored in its database, keeps attempting to renew the certificate with some delay between individual attempts until it can retrieve the updated certificate from the CA renewal master.

The correct functioning of IdM CA renewal master

An IdM deployment with an embedded CA is an IdM deployment that was installed with an IdM CA - or whose IdM CA master server was installed later. An IdM deployment with an embedded CA must at all times have exactly one CA replica configured as the renewal master. The renewal master server must be online and fully functional, and must replicate properly with the other servers.

If the current CA renewal master server is being deleted using the ipa server-del, ipa-replica-manage del, ipa-csreplica-manage del or ipa-server-install --uninstall commands, a CA replica is automatically assigned as the CA renewal master server. This policy ensures that the renewal master configuration remains valid.

This policy does not cover the following situations:

  • Offline renewal master

    • If the renewal master is offline for an extended duration, it may miss a renewal window. In this situation, all nonrenewal master servers keep reinstalling the current system certificates until the certificates expire. When this occurs, the IdM deployment is disrupted because even one expired certificate can cause renewal failures for other certificates. To prevent this situation: if your current renewal master is offline and unavailable for an extended period of time, consider assigning a new CA renewal master manually.
  • Replication problems

    • If replication problems exist between the renewal master and other CA replicas, renewal might succeed, but the other CA replicas might not be able to retrieve the updated certificates before they expire. To prevent this situation, make sure that your replication agreements are working correctly. For details, see general or specific replication troubleshooting guidelines in the RHEL 7 Linux Domain Identity, Authentication, and Policy Guide.

44.2. Changing and resetting IdM CA renewal master

When a certificate authority (CA) renewal master is being decommissioned, Identity Management (IdM) automatically selects a new CA renewal master from the list of IdM CA servers. The system administrator cannot influence the selection.

To be able to select the new IdM CA renewal master server, the system administrator must perform the replacement manually. Select the master before starting the process of decommissioning the current renewal master.

If the current CA renewal master configuration is invalid, reset the IdM CA renewal master.

Complete this procedure to change or reset the CA renewal master.

Prerequisites

  • You have the IdM administrator credentials.

Procedure

  1. Obtain the IdM administrator credentials:

    ~]$ kinit admin
    Password for admin@IDM.EXAMPLE.COM:
  2. Optionally, to find out which IdM servers in the deployment have the CA role necessary to be eligible to become the new CA renewal master:

    ~]$ ipa server-role-find --role 'CA server'
    ----------------------
    2 server roles matched
    ----------------------
      Server name: server.idm.example.com
      Role name: CA server
      Role status: enabled
    
      Server name: replica.idm.example.com
      Role name: CA server
      Role status: enabled
    ----------------------------
    Number of entries returned 2
    ----------------------------

    There are two CA servers in the deployment.

  3. Optionally, to find out which CA server is the current CA renewal master, enter:

    ~]$ ipa config-show | grep 'CA renewal master'
      IPA CA renewal master: server.idm.example.com

    The current renewal master is server.idm.example.com.

  4. To change the renewal master configuration, use the ipa config-mod utility with the --ca-renewal-master-server option:

    ~]$ ipa config-mod --ca-renewal-master-server replica.idm.example.com | grep 'CA renewal master'
      IPA CA renewal master: replica.idm.example.com
    Important

    You can also switch to a new CA renewal master using:

    • the ipa-cacert-manage --renew command. This command both renews the CA certificate and makes the CA server on which you execute the command the new CA renewal master.
    • the ipa-cert-fix command. This command recovers the deployment when expired certificates are causing failures. It also makes the CA server on which you execute the command the new CA renewal master.

      For details, see Renewing expired system certificates when IdM is offline.

44.3. Switching from an externally to self-signed CA in IdM

Complete this procedure to switch from an externally-signed to a self-signed certificate of the Identity Management (IdM) certificate authority (CA). With a self-signed CA, the renewal of the CA certificate is managed automatically: a system administrator does not need to submit a certificate signing request (CSR) to an external authority.

Switching from an externally-signed to a self-signed CA replaces only the CA certificate. The certificates signed by the previous CA are still valid and still in use. For example, the certificate chain for the LDAP certificate remains unchanged even after you have moved to a self-signed CA:

external_CA certificate > IdM CA certificate > LDAP certificate

Prerequisites

  • You have root access to the IdM CA renewal master.
  • You have the IdM administrator credentials.

Procedure

  1. On the IdM CA renewal master, renew the CA certificate as self-signed:

    ~]# ipa-cacert-manage renew --self-signed
    Renewing CA certificate, please wait
    CA certificate successfully renewed
    The ipa-cacert-manage command was successful
  2. On all the IdM servers and clients, update the local IdM certificate databases with the certificates from the server:

    [client ~]$ kinit admin
    [client ~]$ ipa-certupdate
    Systemwide CA database updated.
    Systemwide CA database updated.
    The ipa-certupdate command was successful
  3. Optionally, to check if your update has been successful and the new CA certificate has been added to the /etc/ipa/ca.crt file:

    [client ~]$ openssl crl2pkcs7 -nocrl -certfile /etc/ipa/ca.crt | openssl pkcs7 -print_certs -text -noout
    [...]
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 39 (0x27)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: O=IDM.EXAMPLE.COM, CN=Certificate Authority
            Validity
                Not Before: Jul  1 16:32:45 2019 GMT
                Not After : Jul  1 16:32:45 2039 GMT
            Subject: O=IDM.EXAMPLE.COM, CN=Certificate Authority
    [...]

    The output shows that the update has been successful as the new CA certificate is listed with the older CA certificates.

44.4. Renewing the IdM CA renewal master with an externally-signed certificate

This section describes how to renew the Identity Management (IdM) certificate authority (CA) certificate using an external CA to sign the certificate signing request (CSR). In this configuration, your IdM CA server is a subCA of the external CA. The external CA can, but does not have to, be an Active Directory Certificate Server (AD CS).

If the external certificate authority is AD CS, you can specify the template you want for the IdM CA certificate in the CSR. A certificate template defines the policies and rules that a CA uses when a certificate request is received. Certificate templates in AD correspond to certificate profiles in IdM.

You can define a specific AD CS template by its Object Identifier (OID). OIDs are unique numeric values issued by various issuing authorities to uniquely identify data elements, syntaxes, and other parts of distributed applications.

Alternatively, you can define a specific AD CS template by its name. For example, the name of the default profile used in a CSR submitted by an IdM CA to an AD CS is subCA.

To define a profile by specifying its OID or name in the CSR, use the external-ca-profile option. For details, see the ipa-cacert-manage man page.

Apart from using a ready-made certificate template, you can also create a custom certificate template in the AD CS, and use it in the CSR.

Prerequisites

  • You have root access to the IdM CA renewal master.
  • You have the IdM administrator credentials.

Procedure

Complete this procedure to renew the certificate of the IdM CA with external signing, regardless of whether current CA certificate is self-signed or externally-signed.

  1. Create a CSR to be submitted to the external CA:

    • If the external CA is an AD CS, use the --external-ca-type=ms-cs option. If you want a different template than the default subCA template, specify it using the --external-ca-profile option:

      ~]# ipa-cacert-manage renew --external-ca --external-ca-type=ms-cs [--external-ca-profile=PROFILE]
      Exporting CA certificate signing request, please wait
      The next step is to get /var/lib/ipa/ca.csr signed by your CA and re-run ipa-cacert-manage as:
      ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
      The ipa-cacert-manage command was successful
    • If the external CA is not an AD CS:

      ~]# ipa-cacert-manage renew --external-ca
      Exporting CA certificate signing request, please wait
      The next step is to get /var/lib/ipa/ca.csr signed by your CA and re-run ipa-cacert-manage as:
      ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate
      The ipa-cacert-manage command was successful

      The output shows that a CSR has been created and is stored in the /var/lib/ipa/ca.csr file.

  2. Submit the CSR located in /var/lib/ipa/ca.csr to the external CA. The process differs depending on the service to be used as the external CA.
  3. Retrieve the issued certificate and the CA certificate chain for the issuing CA in a base 64-encoded blob, which is:

    • a PEM file if the external CA is not an AD CS.
    • a Base_64 certificate if the external CA is an AD CS.

      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.

      If the external CA is an AD CS and you have submitted the CSR with a known template through the Microsoft Windows Certification Authority management window, the AD CS issues the certificate immediately and the Save Certificate dialog appears in the AD CS web interface, asking where to save the issued certificate.

  4. Run the ipa-cacert-manage renew command again, adding all the CA certificate files required to supply a full certificate chain. Specify as many files as you need, using the --external-cert-file option multiple times:

    ~]# ipa-cacert-manage renew --external-cert-file=/path/to/signed_certificate --external-cert-file=/path/to/external_ca_certificate_1 --external-cert-file=/path/to/external_ca_certificate_2
  5. On all the IdM servers and clients, update the local IdM certificate databases with the certificates from the server:

    [client ~]$ kinit admin
    [client ~]$ ipa-certupdate
    Systemwide CA database updated.
    Systemwide CA database updated.
    The ipa-certupdate command was successful
  6. Optionally, to check if your update has been successful and the new CA certificate has been added to the /etc/ipa/ca.crt file:

    [client ~]$ openssl crl2pkcs7 -nocrl -certfile /etc/ipa/ca.crt | openssl pkcs7 -print_certs -text -noout
    [...]
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 39 (0x27)
            Signature Algorithm: sha256WithRSAEncryption
            Issuer: O=IDM.EXAMPLE.COM, CN=Certificate Authority
            Validity
                Not Before: Jul  1 16:32:45 2019 GMT
                Not After : Jul  1 16:32:45 2039 GMT
            Subject: O=IDM.EXAMPLE.COM, CN=Certificate Authority
    [...]

    The output shows that the update has been successful as the new CA certificate is listed with the older CA certificates.