Automatically Issue and Renew InCommon Certificates via Certbot (ACME) Without a Web Server or Domain Control Validation (DCV)

Environment

A computer or device that has Certbot installed on it to obtain TLS/SSL certificates.

Issue

A computer or device needs to automatically (without manual intervention from a person) obtain and renew TLS/SSL certificates for itself or for another device, but cannot use the standard Certbot instructions because it does not have a web server and/or cannot perform Domain Control Validation (DCV) for the required DNS names.

Example:  A configuration management system such as Ansible needs to obtain certificates for use by machines it manages, for some reason, instead of running Certbot directly on those machines as it normally would.

Resolution

University staff who manage the InCommon Certificate Service perform Domain Control Validation (DCV) once per year for each domain the university owns.  This means that DCV does not need to be performed again for each InCommon certificate that is issued, the way DCV has to be performed for every certificate with Let's Encrypt.  This also means that an InCommon certificate can be obtained for a domain name without needing either a web server for an HTTP-01 DCV challenge or human intervention or a Certbot DNS plugin for a DNS-01 DCV challenge.  Refer to the Let's Encrypt documentation for more information about DCV challenge types.

CAUTION: do not use these instructions if the standard Certbot instructions will work for you instead. The instructions below are more work, particularly in terms of ensuring that certificates get automatically renewed and deployed before they expire.

1. Ensure you have InCommon ACME credentials (EAB Key ID and EAB HMAC Key for an InCommon ACME endpoint enrollment account) and that those credentials are authorized for the domains you need to obtain and renew certificates for.  If you do not have InCommon ACME credentials or they are not authorized for the domain names you need, refer to Use ACME to Automate Renewals of InCommon Certificates.
2. Make sure Certbot is installed.  Refer to the standard Certbot instructions for details on how to install Certbot.
3. Make sure you have your InCommon Certificate Service credentials in the Certbot configuration file.  On Linux and macOS computers, the configuration file is /etc/letsencrypt/cli.ini   Change the values of email, eab-kid, and eab-hmac-key below to be correct for your InCommon ACME endpoint enrollment account. 
    

   email = your-team-email@umich.edu
   server = https://acme.enterprise.sectigo.com
   eab-kid = xxxxxxxxxx
   eab-hmac-key = yyyyyyyyyyyyyyyyyyyy
   

4. Run the following command to obtain a new certificate.  Replace some-name.some-unit.umich.edu below with the domain name you want to obtain the certificate for.
    

   sudo certbot --verbose certonly \
       --non-interactive \
       --manual \
       --manual-auth-hook /usr/bin/true \
       --domains some-name.some-unit.umich.edu
   

   
   The command above is using /usr/bin/true for the authentication script (--manual-auth-hook value), but you can use any program or script that exits successfully without doing anything.
    
5. Check to see if Certbot set up a cron job or systemd timer for renewing certificates when you installed Certbot.
   1. If Certbot set something up that you don't want to use, disable what Certbot set up and set up instead what ever mechanism you prefer to use to renew the certificate, perhaps incorporating the command in step 6, below.
   2. If Certbot set something up that you want to use, you may need to modify what Certbot set up to use the correct Certbot command line options per step 6, below.
   3. If Certbot did not set anything up for renewing the certificate, you will need to set something up yourself, perhaps incorporating the command in step 6, below.
   4. Be sure to test whatever you wind up with to ensure that it will run properly and actually renew the certificate before the certificate can be renewed.  Keep in mind that a renewal can fail and if it does you should send a notification or alert and attempt the renewal again at the next scheduled time (for example, the next day).
6. The command to renew a certificate is
    

   sudo certbot --verbose renew \
       --force-renewal \
       --non-interactive \
       --manual \
       --manual-auth-hook /usr/bin/true \
       --cert-name some-name.some-unit.umich.edu
   

Additional Information

Also refer to the Certbot documentation.

Contact incommon-certificate-service@umich.edu for more information on certificates.

Need additional information or assistance? Contact the ITS Service Center.