Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 69. Using IdM CA renewal server

69.1. Explanation of IdM CA renewal server

In an Identity Management (IdM) deployment that uses an embedded certificate authority (CA), the CA renewal server maintains and renews IdM system certificates. It ensures robust 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 IdM CA server is the CA renewal server.

Note

In upstream documentation, the IdM CA is called Dogtag.

The role of the CA renewal 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 server, 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 server allows the system certificates to be renewed exactly once, when required, and thus prevents authentication failures.

The role of the certmonger service 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 server configuration. On each CA replica that is not the CA renewal server, the renewal helper 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 server has actually renewed the certificate. If this happens, the old, soon-to-expire certificate is returned to the certmonger service on the CA replica. The certmonger service, 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 server.

The correct functioning of IdM CA renewal server

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

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

This policy does not cover the following situations:

  • Offline renewal server

    If the renewal server is offline for an extended duration, it may miss a renewal window. In this situation, all nonrenewal CA 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 server is offline and unavailable for an extended period of time, consider assigning a new CA renewal server manually.

  • Replication problems

    If replication problems exist between the renewal server 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.

69.2. Changing and resetting IdM CA renewal server

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

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

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

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

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 server: 

    ~]$ 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 server, enter: 

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

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

  4. To change the renewal server 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'
  IPA CA renewal master: replica.idm.example.com
    Important

    You can also switch to a new CA renewal server 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 server.

    • 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 server.

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