26.2. Renewing Certificates

For details on:

26.2.1. Renewing Certificates Automatically

The certmonger service automatically renews the following certificates 28 days before their expiration date:
  • CA certificate issued by the IdM CA as the root CA
  • Subsystem and server certificates issued by the integrated IdM CA that are used by internal IdM services
To automatically renew sub-CA CA certificates, they must be listed on the certmonger tracking list. To update the tracking list:
[root@ipaserver ~]# ipa-certupdate
trying https://idmserver.idm.example.com/ipa/json
Forwarding 'schema' to json server 'https://idmserver.idm.example.com/ipa/json'
trying https://idmserver.idm.example.com/ipa/json
Forwarding 'ca_is_enabled' to json server 'https://idmserver.idm.example.com/ipa/json'
Forwarding 'ca_find/1' to json server 'https://idmserver.idm.example.com/ipa/json'
Systemwide CA database updated.
Systemwide CA database updated.
The ipa-certupdate command was successful

Note

If you are using an external CA as the root CA, you must renew the certificates manually, as described in Section 26.2.2, “Renewing CA Certificates Manually”. The certmonger service cannot automatically renew certificates signed by an external CA.
For more information on how certmonger monitors certificate expiration dates, see Tracking Certificates with certmonger in the System-Level Authentication Guide.
To verify that automatic renewal works as expected, examine certmonger log messages in the /var/log/messages file:
  • After a certificate is renewed, certmonger records message like the following to indicate that the renewal operation has succeeded or failed:
    Certificate named "NSS Certificate DB" in token "auditSigningCert cert-pki-ca" in database "/var/lib/pki-ca/alias" renew success
  • As the certificate nears its expiration, certmonger logs the following message:
    certmonger: Certificate named "NSS Certificate DB" in token "auditSigningCert cert-pki-ca" in database "/var/lib/pki-ca/alias" will not be valid after 20160204065136.

26.2.2. Renewing CA Certificates Manually

You can use the ipa-cacert-manage utility to manually renew:
  • self-signed IdM CA certificate
  • externally-signed IdM CA certificate
The certificates renewed with the ipa-cacert-manage renew command use the same key pair and subject name as the old certificates. Renewing a certificate does not remove its previous version to enable certificate rollover.
For details, see the ipa-cacert-manage(1) man page.

26.2.2.1. Renewing a Self-Signed IdM CA Certificate Manually

  1. Run the ipa-cacert-manage renew command. The command does not require you to specify the path to the certificate.
  2. The renewed certificate is now present in the LDAP certificate store and in the /etc/pki/pki-tomcat/alias NSS database.
  3. Run the ipa-certupdate utility on all servers and clients to update them with the information about the new certificate from LDAP. You must run ipa-certupdate on every server and client separately.

    Important

    Always run ipa-certupdate after manually installing a certificate. If you do not, the certificate will not be distributed to the other machines.
To make sure the renewed certificate is properly installed, use the certutil utility to list the certificates in the database. For example:
# certutil -L -d /etc/pki/pki-tomcat/alias

26.2.2.2. Renewing an Externally-Signed IdM CA Certificate Manually

  1. Run the ipa-cacert-manage renew --external-ca command.
  2. The command creates the /var/lib/ipa/ca.crt CSR file. Submit the CSR to the external CA to get the renewed CA certificate issued.
  3. Run ipa-cacert-manage renew again, and this time specify the renewed CA certificate and the external CA certificate chain files using the --external-cert-file option. For example:
    # ipa-cacert-manage renew --external-cert-file=/tmp/servercert20110601.pem --external-cert-file=/tmp/cacert.pem
  4. The renewed CA certificate and the external CA certificate chain are now present in the LDAP certificate store and in the /etc/pki/pki-tomcat/alias/ NSS database.
  5. Run the ipa-certupdate utility on all servers and clients to update them with the information about the new certificate from LDAP. You must run ipa-certupdate on every server and client separately.

    Important

    Always run ipa-certupdate after manually installing a certificate. If you do not, the certificate will not be distributed to the other machines.
To make sure the renewed certificate is properly installed, use the certutil utility to list the certificates in the database. For example:
# certutil -L -d /etc/pki/pki-tomcat/alias/

26.2.3. Renewing Expired System Certificates When IdM is Offline

When a system certificate has expired, IdM fails to start. IdM on Red Hat Enterprise Linux 7.7 or later supports renewing system certificates when IdM is offline.
The following procedure describes how to renew all expired system certificates on IdM servers:
  1. On a CA in the IdM domain:
    1. Start the ipa-cert-fix utility to analyse the system and list expired certificates:
      # ipa-cert-fix
      ...
      The following certificates will be renewed:
      
      Dogtag sslserver certificate:
        Subject: CN=ca1.example.com,O=EXAMPLE.COM 201905222205
        Serial:  13
        Expires: 2019-05-12 05:55:47
      ...
      Enter "yes" to proceed:
    2. Enter yes to start the renewal process:
      Enter "yes" to proceed: yes
      Proceeding.
      Renewed Dogtag sslserver certificate:
        Subject: CN=ca1.example.com,O=EXAMPLE.COM 201905222205
        Serial:  268369925
        Expires: 2021-08-14 02:19:33
      ...
      
      Becoming renewal master.
      The ipa-cert-fix command was successful
      It can take up to one minute before ipa-cert-fix renews all expired certificates.

      Note

      If you ran the ipa-cert-fix utility on a CA host that was not the renewal master, and the utility renewed shared certificates, this host automatically becomes the new renewal master in the domain. There must be always only one renewal master in the domain to avoid inconsistencies.
    3. Optionally, verify that all services are running:
      # ipactl status
      Directory Service: RUNNING
      krb5kdc Service: RUNNING
      kadmin Service: RUNNING
      httpd Service: RUNNING
      ipa-custodia Service: RUNNING
      pki-tomcatd Service: RUNNING
      ipa-otpd Service: RUNNING
      ipa: INFO: The ipactl command was successful
  2. On other servers in the IdM domain:
    1. Restart IdM with the --force parameter:
      # ipactl restart --force
      With the --force parameter, the ipactl utility ignores individual startup failures. For example, if the server is also a CA, the pki-tomcat service fails to start. This is expected and ignored because of using the --force parameter.
    2. After the restart, verify that the certmonger service renewed the certificates:
      # getcert list | egrep '^Request|status:|subject:'
      Request ID '20190522120745':
              status: MONITORING
              subject: CN=IPA RA,O=EXAMPLE.COM 201905222205
      Request ID '20190522120834':
              status: MONITORING
              subject: CN=Certificate Authority,O=EXAMPLE.COM 201905222205
      ...
      Note that it can take some time before certmonger renews the shared certificates on the replica.
    3. If the server is also a CA, the previous command reports CA_UNREACHABLE for the certificate the pki-tomcat service uses:
      Request ID '20190522120835':
              status: CA_UNREACHABLE
              subject: CN=ca2.example.com,O=EXAMPLE.COM 201905222205
      ...
      To renew this certificate, use the ipa-cert-fix utility:
      # ipa-cert-fix
      Dogtag sslserver certificate:
        Subject: CN=ca2.example.com,O=EXAMPLE.COM
        Serial:  3
        Expires: 2019-05-11 12:07:11
      
      Enter "yes" to proceed: yes
      Proceeding.
      Renewed Dogtag sslserver certificate:
        Subject: CN=ca2.example.com,O=EXAMPLE.COM 201905222205
        Serial:  15
        Expires: 2019-08-14 04:25:05
      
      The ipa-cert-fix command was successful