Chapter 19. Obtaining an IdM certificate for a service using certmonger 19.1. Certmonger overview When Identity Management (IdM) is installed with an integrated IdM Certificate Authority (CA), it uses the certmonger service to track and renew system and service certificates. When the certificate is reaching its expiration date, certmonger manages the renewal process by: Regenerating a certificate-signing request (CSR) using the options provided in the original request. Submitting the CSR to the IdM CA using the IdM API cert-request command. Receiving the certificate from the IdM CA. Executing a pre-save command if specified by the original request. Installing the new certificate in the location specified in the renewal request: either in an NSS database or in a file. Executing a post-save command if specified by the original request. For example, the post-save command can instruct certmonger to restart a relevant service, so that the service picks up the new certificate. Types of certificates certmonger tracks Certificates can be divided into system and service certificates. Unlike service certificates (for example, for HTTP , LDAP and PKINIT ), which have different keypairs and subject names on different servers, IdM system certificates and their keys are shared by all CA replicas. The 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 The certmonger service tracks the IdM system and service certificates that were requested during the installation of IdM environment with an integrated CA. Certmonger also tracks certificates that have been requested manually by the system administrator for other services running on the IdM host. Certmonger does not track external CA certificates or user certificates. Certmonger components The certmonger service consists of two main components: The certmonger daemon , which is the engine tracking the list of certificates and launching renewal commands The getcert utility for the command line (CLI), which allows the system administrator to actively send commands to the certmonger daemon. More specifically, the system administrator can use the getcert utility to: Request a new certificate View the list of certificates that certmonger tracks Start or stop tracking a certificate Renew a certificate 19.2. Obtaining an IdM certificate for a service using certmonger To ensure that communication between browsers and the web service running on your Identity Management (IdM) client is secure and encrypted, use a TLS certificate. Obtain the TLS certificate for your web service from the IdM Certificate Authority (CA). Follow this procedure to use certmonger to obtain an IdM certificate for a service ( HTTP/my_company.idm.example.com @ IDM.EXAMPLE.COM ) running on an IdM client. Using certmonger to request the certificate automatically means that certmonger manages and renews the certificate when it is due for a renewal. For a visual representation of what happens when certmonger requests a service certificate, see Section 19.3, "Communication flow for certmonger requesting a service certificate" . Prerequisites The web server is enrolled as an IdM client. You have root access to the IdM client on which you are running the procedure. The service for which you are requesting a certificate does not have to pre-exist in IdM. Procedure On the my_company.idm.example.com IdM client on which the HTTP service is running, request a certificate for the service corresponding to the HTTP/my_company.idm.example.com@IDM.EXAMPLE.COM principal, and specify that The certificate is to be stored in the local /etc/pki/tls/certs/httpd.pem file The private key is to be stored in the local /etc/pki/tls/private/httpd.key file That an extensionRequest for a SubjectAltName be added to the signing request with the DNS name of my_company.idm.example.com : In the command above: The ipa-getcert request command specifies that the certificate is to be obtained from the IdM CA. The ipa-getcert request command is a shortcut for getcert request -c IPA . The -g option specifies the size of key to be generated if one is not already in place. The -D option specifies the SubjectAltName DNS value to be added to the request. The -C option instructs certmonger to restart the httpd service after obtaining the certificate. To specify that the certificate be issued with a particular profile, use the -T option. To request a certificate using the named issuer from the specified CA, use the -X ISSUER option. Optional: To check the status of your request: The output shows that the request is in the MONITORING status, which means that a certificate has been obtained. The locations of the key pair and the certificate are those requested. 19.3. Communication flow for certmonger requesting a service certificate These diagrams show the stages of what happens when certmonger requests a service certificate from Identity Management (IdM) certificate authority (CA) server. The sequence consists of these diagrams: Unencrypted communication Certmonger requesting a service certificate IdM CA issuing the service certificate Certmonger applying the service certificate Certmonger requesting a new certificate when the old one is nearing expiration Unencrypted communication shows the initial situation: without an HTTPS certificate, the communication between the web server and the browser is unencrypted. Figure 19.1. Unencrypted communication Certmonger requesting a service certificate shows the system administrator using certmonger to manually request an HTTPS certificate for the Apache web server. Note that when requesting a web server certificate, certmonger does not communicate directly with the CA. It proxies through IdM. Figure 19.2. Certmonger requesting a service certificate IdM CA issuing the service certificate shows an IdM CA issuing an HTTPS certificate for the web server. Figure 19.3. IdM CA issuing the service certificate Certmonger applying the service certificate shows certmonger placing the HTTPS certificate in appropriate locations on the IdM client and, if instructed to do so, restarting the httpd service. The Apache server subsequently uses the HTTPS certificate to encrypt the traffic between itself and the browser. Figure 19.4. Certmonger applying the service certificate Certmonger requesting a new certificate when the old one is nearing expiration shows certmonger automatically requesting a renewal of the service certificate from the IdM CA before the expiration of the certificate. The IdM CA issues a new certificate. Figure 19.5. Certmonger requesting a new certificate when the old one is nearing expiration 19.4. Viewing the details of a certificate request tracked by certmonger The certmonger service monitors certificate requests. When a request for a certificate is successfully signed, it results in a certificate. Certmonger manages certificate requests including the resulting certificates. Follow this procedure to view the details of a particular certificate request managed by certmonger . Procedure If you know how to specify the certificate request, list the details of only that particular certificate request. You can, for example, specify: The request ID The location of the certificate The certificate nickname For example, to view the details of the certificate whose request ID is 20190408143846, using the -v option to view all the details of errors in case your request for a certificate was unsuccessful: The output displays several pieces of information about the certificate, for example: the certificate location; in the example above, it is the NSS database in the /etc/dirsrv/slapd-IDM-EXAMPLE-COM directory the certificate nickname; in the example above, it is Server-Cert the file storing the pin; in the example above, it is /etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt the Certificate Authority (CA) that will be used to renew the certificate; in the example above, it is the IPA CA the expiration date; in the example above, it is 2021-04-08 16:38:47 CEST the status of the certificate; in the example above, the MONITORING status means that the certificate is valid and it is being tracked the post-save command; in the example above, it is the restart of the LDAP service If you do not know how to specify the certificate request, list the details of all the certificates that certmonger is monitoring or attempting to obtain: Additional resources See the getcert list man page on your system. 19.5. Starting and stopping certificate tracking Follow this procedure to use the getcert stop-tracking and getcert start-tracking commands to monitor certificates. The two commands are provided by the certmonger service. Enabling certificate tracking is especially useful if you have imported a certificate issued by the Identity Management (IdM) certificate authority (CA) onto the machine from a different IdM client. Enabling certificate tracking can also be the final step of the following provisioning scenario: On the IdM server, you create a certificate for a system that does not exist yet. You create the new system. You enroll the new system as an IdM client. You import the certificate and the key from the IdM server on to the IdM client. You start tracking the certificate using certmonger to ensure that it gets renewed when it is due to expire. Procedure To disable the monitoring of a certificate with the Request ID of 20190408143846: For more options, see the getcert stop-tracking man page on your system. To enable the monitoring of a certificate stored in the /tmp/some_cert.crt file, whose private key is stored in the /tmp/some_key.key file: Certmonger cannot automatically identify the CA type that issued the certificate. For this reason, add the -c option with the IPA value to the getcert start-tracking command if the certificate was issued by the IdM CA. Omitting to add the -c option results in certmonger entering the NEED_CA state. For more options, see the getcert start-tracking man page on your system. Note The two commands do not manipulate the certificate. For example, getcert stop-tracking does not delete the certificate or remove it from the NSS database or from the filesystem but simply removes the certificate from the list of monitored certificates. Similarly, getcert start-tracking only adds a certificate to the list of monitored certificates. 19.6. Renewing a certificate manually When a certificate is near its expiration date, the certmonger daemon automatically issues a renewal command using the certificate authority (CA) helper, obtains a renewed certificate and replaces the certificate with the new one. You can also manually renew a certificate in advance by using the getcert resubmit command. This way, you can update the information the certificate contains, for example, by adding a Subject Alternative Name (SAN). Follow this procedure to renew a certificate manually. Procedure To renew a certificate with the Request ID of 20190408143846: To obtain the Request ID for a specific certificate, use the getcert list command. For details, see the getcert list man page on your system. 19.7. Making certmonger resume tracking of IdM certificates on a CA replica This procedure shows how to make certmonger resume the tracking of Identity Management (IdM) system certificates that are crucial for an IdM deployment with an integrated certificate authority after the tracking of certificates was interrupted. The interruption may have been caused by the IdM host being unenrolled from IdM during the renewal of the system certificates or by replication topology not working properly. The procedure also shows how to make certmonger resume the tracking of the IdM service certificates, namely the HTTP , LDAP and PKINIT certificates. Prerequisites The host on which you want to resume tracking system certificates is an IdM server that is also an IdM certificate authority (CA) but not the IdM CA renewal server. Procedure Get the PIN for the subsystem CA certificates: Add tracking to the subsystem CA certificates, replacing [internal PIN] in the commands below with the PIN obtained in the step: Add tracking for the remaining IdM certificates, the HTTP , LDAP , IPA renewal agent and PKINIT certificates: Restart certmonger : Wait for one minute after certmonger has started and then check the statuses of the new certificates: Note the following: If your IdM system certificates have all expired, see the Red Hat Knowledgebase solution How do I manually renew Identity Management (IPA) certificates on RHEL7/RHEL 8 after they have expired? to manually renew IdM system certificates on the IdM CA server that is also the CA renewal server and the CRL publisher server. Follow the procedure described in the Red Hat Knowledgebase solution How do I manually renew Identity Management (IPA) certificates on RHEL7 after they have expired? to manually renew IdM system certificates on all the other CA servers in the topology. 19.8. Using SCEP with certmonger The Simple Certificate Enrollment Protocol (SCEP) is a certificate management protocol that you can use across different devices and operating systems. If you are using a SCEP server as an external certificate authority (CA) in your environment, you can use certmonger to obtain a certificate for an Identity Management (IdM) client. 19.8.1. SCEP overview The Simple Certificate Enrollment Protocol (SCEP) is a certificate management protocol that you can use across different devices and operating systems. You can use a SCEP server as an external certificate authority (CA). You can configure an Identity Management (IdM) client to request and retrieve a certificate over HTTP directly from the CA SCEP service. This process is secured by a shared secret that is usually valid only for a limited time. On the client side, SCEP requires you to provide the following components: SCEP URL: the URL of the CA SCEP interface. SCEP shared secret: a challengePassword PIN shared between the CA and the SCEP client, used to obtain the certificate. The client then retrieves the CA certificate chain over SCEP and sends a certificate signing request to the CA. When configuring SCEP with certmonger , you create a new CA configuration profile that specifies the issued certificate parameters. 19.8.2. Requesting an IdM CA-signed certificate through SCEP The following example adds a SCEP_example SCEP CA configuration to certmonger and requests a new certificate on the client.idm.example.com IdM client. certmonger supports both the NSS certificate database format and file-based (PEM) formats, such as OpenSSL. Prerequisites You know the SCEP URL. You have the challengePassword PIN shared secret. Procedure Add the CA configuration to certmonger : -c : Mandatory nickname for the CA configuration. The same value can later be used with other getcert commands. -u : URL of the server's SCEP interface. Important When using an HTTPS URL, you must also specify the location of the PEM-formatted copy of the SCEP server CA certificate using the -R option. Verify that the CA configuration has been successfully added: If the configuration was successfully added, certmonger retrieves the CA chain from the remote CA. The CA chain then appears as thumbprints in the command output. When accessing the server over unencrypted HTTP, manually compare the thumbprints with the ones displayed at the SCEP server to prevent a man-in-the-middle attack. Request a certificate from the CA: If you are using NSS: You can use the options to specify the following parameters of the certificate request: -I : (Optional) Name of the task: the tracking ID for the request. The same value can later be used with the getcert list command. -c : CA configuration to submit the request to. -d : Directory with the NSS database to store the certificate and key. -n : Nickname of the certificate, used in the NSS database. -N : Subject name in the CSR. -L : Time-limited one-time challengePassword PIN issued by the CA. -D : Subject Alternative Name for the certificate, usually the same as the host name. If you are using OpenSSL: You can use the options to specify the following parameters of the certificate request: -I : (Optional) Name of the task: the tracking ID for the request. The same value can later be used with the getcert list command. -c : CA configuration to submit the request to. -f : Storage path to the certificate. -k : Storage path to the key. -N : Subject name in the CSR. -L : Time-limited one-time challengePassword PIN issued by the CA. -D : Subject Alternative Name for the certificate, usually the same as the host name. Verification Verify that a certificate was issued and correctly stored in the local database: If you used NSS, enter: If you used OpenSSL, enter: The status MONITORING signifies a successful retrieval of the issued certificate. The getcert-list(1) man page lists other possible states and their meanings. Additional resources For more options when requesting a certificate, see the getcert-request(1) man page on your system. 19.8.3. Automatically renewing AD SCEP certificates with certmonger When certmonger sends a SCEP certificate renewal request, this request is signed using the existing certificate private key. However, renewal requests sent by certmonger by default also include the challengePassword PIN that was used to originally obtain the certificates. An Active Directory (AD) Network Device Enrollment Service (NDES) server that works as the SCEP server automatically rejects any requests for renewal that contain the original challengePassword PIN. Consequently, the renewal fails. For renewal with AD to work, you need to configure certmonger to send the signed renewal requests without the challengePassword PIN. You also need to configure the AD server so that it does not compare the subject name at renewal. Note There may be SCEP servers other than AD that also refuse requests containing the challengePassword . In those cases, you may also need to change the certmonger configuration in this way. Prerequisites The RHEL server has to be running RHEL 8.6 or newer. Procedure Open regedit on the AD server. In the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\MSCEP subkey, add a new 32-bit REG_DWORD entry DisableRenewalSubjectNameMatch and set its value to 1 . On the server where certmonger is running, open the /etc/certmonger/certmonger.conf file and add the following section: Restart certmonger:

Commands:
ipa-getcert request -K HTTP/my_company.idm.example.com -k /etc/pki/tls/private/httpd.key -f /etc/pki/tls/certs/httpd.pem -g 2048 -D my_company.idm.example.com -C "systemctl restart httpd" New signing request "20190604065735" added.
ipa-getcert list -f /etc/pki/tls/certs/httpd.pem Number of certificates and requests being tracked: 3. Request ID '20190604065735': status: MONITORING stuck: no key pair storage: type=FILE,location='/etc/pki/tls/private/httpd.key' certificate: type=FILE,location='/etc/pki/tls/certs/httpd.crt' CA: IPA [...]
getcert list -i 20190408143846 -v Number of certificates and requests being tracked: 16. Request ID '20190408143846': status: MONITORING stuck: no key pair storage: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB',pinfile='/etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt' certificate: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB' CA: IPA issuer: CN=Certificate Authority,O=IDM.EXAMPLE.COM subject: CN=r8server.idm.example.com,O=IDM.EXAMPLE.COM expires: 2021-04-08 16:38:47 CEST dns: r8server.idm.example.com principal name: ldap/server.idm.example.com@IDM.EXAMPLE.COM key usage: digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment eku: id-kp-serverAuth,id-kp-clientAuth pre-save command: post-save command: /usr/libexec/ipa/certmonger/restart_dirsrv IDM-EXAMPLE-COM track: true auto-renew: true
getcert list
getcert stop-tracking -i 20190408143846
getcert start-tracking -c IPA -f /tmp/some_cert.crt -k /tmp/some_key.key
getcert resubmit -i 20190408143846
grep 'internal=' /var/lib/pki/pki-tomcat/conf/password.conf
getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "caSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "caSigningCert cert-pki-ca"' -T caCACert getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "auditSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "auditSigningCert cert-pki-ca"' -T caSignedLogCert getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "ocspSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "ocspSigningCert cert-pki-ca"' -T caOCSPCert getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "subsystemCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "subsystemCert cert-pki-ca"' -T caSubsystemCert getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "Server-Cert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "Server-Cert cert-pki-ca"' -T caServerCert
getcert start-tracking -f /var/lib/ipa/certs/httpd.crt -k /var/lib/ipa/private/httpd.key -p /var/lib/ipa/passwds/idm.example.com-443-RSA -c IPA -C /usr/libexec/ipa/certmonger/restart_httpd -T caIPAserviceCert getcert start-tracking -d /etc/dirsrv/slapd-IDM-EXAMPLE-COM -n "Server-Cert" -c IPA -p /etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt -C '/usr/libexec/ipa/certmonger/restart_dirsrv "IDM-EXAMPLE-COM"' -T caIPAserviceCert getcert start-tracking -f /var/lib/ipa/ra-agent.pem -k /var/lib/ipa/ra-agent.key -c dogtag-ipa-ca-renew-agent -B /usr/libexec/ipa/certmonger/renew_ra_cert_pre -C /usr/libexec/ipa/certmonger/renew_ra_cert -T caSubsystemCert getcert start-tracking -f /var/kerberos/krb5kdc/kdc.crt -k /var/kerberos/krb5kdc/kdc.key -c dogtag-ipa-ca-renew-agent -B /usr/libexec/ipa/certmonger/renew_ra_cert_pre -C /usr/libexec/ipa/certmonger/renew_kdc_cert -T KDCs_PKINIT_Certs
systemctl restart certmonger
getcert list
getcert add-scep-ca -c SCEP_example -u SCEP_URL
getcert list-cas -c SCEP_example CA 'SCEP_example': is-default: no ca-type: EXTERNAL helper-location: /usr/libexec/certmonger/scep-submit -u http://SCEP_server_enrollment_interface_URL SCEP CA certificate thumbprint (MD5): A67C2D4B 771AC186 FCCA654A 5E55AAF7 SCEP CA certificate thumbprint (SHA1): FBFF096C 6455E8E9 BD55F4A5 5787C43F 1F512279
getcert request -I Example_Task -c SCEP_example -d /etc/pki/nssdb -n ExampleCert -N cn=" client.idm.example.com " -L one-time_PIN -D client.idm.example.com
getcert request -I Example_Task -c SCEP_example -f /etc/pki/tls/certs/server.crt -k /etc/pki/tls/private/private.key -N cn=" client.idm.example.com " -L one-time_PIN -D client.idm.example.com
getcert list -I Example_Task Request ID 'Example_Task': status: MONITORING stuck: no key pair storage: type=NSSDB,location='/etc/pki/nssdb',nickname='ExampleCert',token='NSS Certificate DB' certificate: type=NSSDB,location='/etc/pki/nssdb',nickname='ExampleCert',token='NSS Certificate DB' signing request thumbprint (MD5): 503A8EDD DE2BE17E 5BAA3A57 D68C9C1B signing request thumbprint (SHA1): B411ECE4 D45B883A 75A6F14D 7E3037F1 D53625F4 CA: IPA issuer: CN=Certificate Authority,O=EXAMPLE.COM subject: CN=client.idm.example.com,O=EXAMPLE.COM expires: 2018-05-06 10:28:06 UTC key usage: digitalSignature,keyEncipherment eku: iso.org.dod.internet.security.mechanisms.8.2.2 certificate template/profile: IPSECIntermediateOffline pre-save command: post-save command: track: true auto-renew: true
getcert list -I Example_Task Request ID 'Example_Task': status: MONITORING stuck: no key pair storage: type=FILE,location='/etc/pki/tls/private/private.key' certificate: type=FILE,location='/etc/pki/tls/certs/server.crt' CA: IPA issuer: CN=Certificate Authority,O=EXAMPLE.COM subject: CN=client.idm.example.com,O=EXAMPLE.COM expires: 2018-05-06 10:28:06 UTC eku: id-kp-serverAuth,id-kp-clientAuth pre-save command: post-save command: track: true auto-renew: true
[scep] challenge_password_otp = yes
systemctl restart certmonger