Chapter 48. Obtaining an IdM certificate for a service using certmonger
48.1. Certmonger overview
What certmonger
does
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 thecommand-line interface
(CLI), which allows the system administrator to actively send commands to thecertmonger
daemon.
More specifically, the system administrator can use the getcert
utility to:
48.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).
This section describes how 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 48.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 theHTTP
service is running, request a certificate for the service corresponding to theHTTP/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 ofmy_company.idm.example.com
:# 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.
In the command above:
-
The
ipa-getcert request
command specifies that the certificate is to be obtained from the IdM CA. Theipa-getcert request
command is a shortcut forgetcert 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 theSubjectAltName
DNS value to be added to the request. -
The
-C
option instructscertmonger
to restart thehttpd
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.
NoteRHEL 8 uses a different SSL module in Apache than the one used in RHEL 7. The SSL module relies on OpenSSL rather than NSS. For this reason, in RHEL 8 you cannot use an NSS database to store the
HTTPS
certificate and the private key.-
The
-
The certificate is to be stored in the local
Optionally, to check the status of your request:
# 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 [...]
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.
48.3. Communication flow for certmonger requesting a service certificate
The diagrams in this section 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:
- Figure 48.1, “Unencrypted communication”
- Figure 48.2, “Certmonger requesting a service certificate”
- Figure 48.3, “IdM CA issuing the service certificate”
- Figure 48.4, “Certmonger applying the service certificate”
- Figure 48.5, “Certmonger requesting a new certificate when the old one is nearing expiration”
Figure 48.1, “Unencrypted communication” shows the initial situation: without an HTTPS certificate, the communication between the web server and the browser is unencrypted.
Figure 48.1. Unencrypted communication

Figure 48.2, “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 48.2. Certmonger requesting a service certificate

Figure 48.3, “IdM CA issuing the service certificate” shows an IdM CA issuing an HTTPS certificate for the web server.
Figure 48.3. IdM CA issuing the service certificate

Figure 48.4, “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 48.4. Certmonger applying the service certificate

Figure 48.5, “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 48.5. Certmonger requesting a new certificate when the old one is nearing expiration

48.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. This section describes how 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:# 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: yes auto-renew: yes
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:# getcert list
Additional information
-
To view the different options how to specify the certificate request displayed, see the
getcert list
man page.
48.5. Starting and stopping certificate tracking
This section describes how you can 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:
# getcert stop-tracking -i 20190408143846
For more options, see the
getcert stop-tracking
man page.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:# getcert start-tracking -c IPA -f /tmp/some_cert.crt -k /tmp/some_key.key
Certmonger
cannot automatically identify the CA type that issued the certificate. For this reason, add the-c
option with theIPA
value to thegetcert start-tracking
command if the certificate was issued by the IdM CA. Omitting to add the-c
option results incertmonger
entering the NEED_CA state.For more options, see the
getcert start-tracking
man page.
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.
48.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 previous certificate with the new one.
It is also possible to manually renew a certificate in advance by using the getcert resubmit
command. This way, you can update the information the certificate contains, e.g. by adding a Subject Alternative Name (SAN).
This section describes how to renew a certificate manually.
Procedure
To renew a certificate with the Request ID of 20190408143846:
# getcert resubmit -i 20190408143846
To obtain the Request ID for a specific certificate, use the
getcert list
command. For details, see thegetcert list
man page.
48.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:
# grep 'internal=' /var/lib/pki/pki-tomcat/conf/password.conf
Add tracking to the subsystem CA certificates, replacing
[internal PIN]
in the commands below with the PIN obtained in the previous step:# 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"' # 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"' # 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"' # 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"' # 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"'
Add tracking for the remaining IdM certificates, the
HTTP
,LDAP
,IPA renewal agent
andPKINIT
certificates:# 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 # 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"' # 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 # 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
Restart
certmonger
:# systemctl restart certmonger
Wait for one minute after
certmonger
has started and then check the statuses of the new certificates:# getcert list
Additional resources
- If your IdM system certificates have all expired, follow the procedure described in this Knowledge Centered Support (KCS) solution to manually renew IdM system certificates on the IdM CA server that is also the CA renewal server and the CRL publisher server. Then follow the procedure described in this KCS solution to manually renew IdM system certificates on all the other CA servers in the topology.