Chapter 15. Obtaining an IdM certificate for a service using certmonger
15.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
- 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
NSSdatabase or in a file.
executing a post-save command if specified by the original request. For example, the post-save command can instruct
certmongerto restart a relevant service, so that the service picks up the new certificate.
Types of certificates
Certificates can be divided into system and service certificates.
Unlike service certificates (for example, for
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 subsystemcertificates
IdM CA audit signingcertificate
IdM renewal agent(RA) certificate
KRAtransport and storage certificates
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 service consists of two main components:
certmonger daemon, which is the engine tracking the list of certificates and launching renewal commands
getcertutility for the
command-line interface(CLI), which allows the system administrator to actively send commands to the
More specifically, the system administrator can use the
getcert utility to:
15.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 (
IDM.EXAMPLE.COM) running on an IdM client.
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 15.3, “Communication flow for certmonger requesting a service certificate”.
- 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.
my_company.idm.example.comIdM client on which the
HTTPservice is running, request a certificate for the service corresponding to the
HTTP/my_company.idm.example.com@IDM.EXAMPLE.COMprincipal, and specify that
The certificate is to be stored in the local
The private key is to be stored in the local
That an extensionRequest for a
SubjectAltNamebe added to the signing request with the DNS name of
# 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:
ipa-getcert requestcommand specifies that the certificate is to be obtained from the IdM CA. The
ipa-getcert requestcommand is a shortcut for
getcert request -c IPA.
-goption specifies the size of key to be generated if one is not already in place.
-Doption specifies the
SubjectAltNameDNS value to be added to the request.
certmongerto restart the
httpdservice after obtaining the certificate.
To specify that the certificate be issued with a particular profile, use the
To request a certificate using the named issuer from the specified CA, use 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
MONITORINGstatus, which means that a certificate has been obtained. The locations of the key pair and the certificate are those requested.
15.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:
Unencrypted communication shows the initial situation: without an HTTPS certificate, the communication between the web server and the browser is unencrypted.
Figure 15.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 15.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 15.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 15.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 15.5. Certmonger requesting a new certificate when the old one is nearing expiration
15.4. Viewing the details of a certificate request tracked by certmonger
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
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
-voption 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
the certificate nickname; in the example above, it is
the file storing the pin; in the example above, it is
the Certificate Authority (CA) that will be used to renew the certificate; in the example above, it is the
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
MONITORINGstatus 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
If you do not know how to specify the certificate request, list the details of all the certificates that
certmongeris monitoring or attempting to obtain:
# getcert list
getcert listman page.
15.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
certmongerto ensure that it gets renewed when it is due to expire.
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-trackingman page.
To enable the monitoring of a certificate stored in the
/tmp/some_cert.crtfile, whose private key is stored in the
# getcert start-tracking -c IPA -f /tmp/some_cert.crt -k /tmp/some_key.key
Certmongercannot automatically identify the CA type that issued the certificate. For this reason, add the
-coption with the
IPAvalue to the
getcert start-trackingcommand if the certificate was issued by the IdM CA. Omitting to add the
-coption results in
certmongerentering the NEED_CA state.
For more options, see the
getcert start-trackingman 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.
15.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.
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 listcommand. For details, see the
getcert listman page.
15.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
- 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.
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 -T caCACert "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 -T caSignedLogCert "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 -T caOCSPCert "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 -T caSubsystemCert "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 -T caServerCert "Server-Cert cert-pki-ca"'
Add tracking for the remaining IdM certificates, the
IPA renewal agentand
# 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 -T caIPAserviceCert "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 -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
Wait for one minute after
certmongerhas started and then check the statuses of the new certificates:
# getcert list
- If your IdM system certificates have all expired, see 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.