Use ACME to Automate Renewals of InCommon Certificates

This document describes how to implement the Automatic Certificate Management Environment (ACME) protocol to automate the renewal process between the InCommon certificate authority and your systems. Applicable systems include any system or service that runs Microsoft Windows or Linux, including network appliances, scientific instruments, directory servers, file servers, mail servers, video conferencing systems, and more.

Notes:

  • Units that are eligible to use the InCommon Certificate Manager (ICM) webapp can manage, view, and generate reports on their ACME certificates via the ICM webapp.
  • You can also use ACME to obtain certificates from the Let’s Encrypt certificate authority.  For instructions on how to use ACME to obtain certificates from Let’s Encrypt, please see the Let’s Encrypt website.  This document covers only how to use ACME to obtain InCommon certificates.

Contents

Overview

ITS recommends that you use the ACME protocol to prevent your InCommon certificates from expiring inadvertently. An automated approach for managing the renewal of InCommon certificates is also quicker than using Web Application Sign Up (WASUP) service for those that manage a large number of certificates.
ACME is only available to U-M IT staff or students providing IT support to units.

Domain Requirements

The following types of domains are approved for use with ACME:

  • Main domain under umich.edu (for example, med.umich.edu)
  • Subdomain under umich.edu that you fully control and are not shared (for example, mhealthy.umich.edu)
  • Domains that a unit purchased that are not under umich.edu (for example, mmheadlines.org)

InCommon Versus Let’s Encrypt Comparison

Units can choose the option they want to use, but ITS recommends ACME + InCommon wherever possible. This enables the university to have visibility into which certificates exist and more easily provide support for them.
 

  ACME + InCommon ACME + Let’s Encrypt
Maximum certificate validity 365 days 90 days
Who can use it? U-M units Anyone at U-M
Obtain and install certificates fully automatically Yes Yes
Renew certificates fully automatically Yes Yes
Does each ACME client need to successfully complete a challenge for Domain Control Validation? No (all umich.edu domains have been pre-validated) Yes
ACME credentials used to initially set up a new server or device Obtained and installed manually
(request cred form + manual cred install)
Obtained automatically
(install client which will then request creds and install)
Central management and reporting Yes, for ITS and units that have access to the InCommon Certificate Manager web app No
Staging environment Currently disabled for U-M Yes

Enrollment and Configuration Process

Set up enrollment account

  1. Submit a request to set up an endpoint enrollment account(s). In the email, include a list of uniqnames to receive access and your subdomains for which you will issue certificates.

Notes:

  • There are two approaches to establishing endpoint enrollment accounts, depending on your infrastructure management and security requirements:
    • Request one endpoint enrollment account to be used with all servers. This is the standard approach.
    • If you have special security concerns with using an endpoint enrollment account across multiple systems, request an endpoint enrollment account for each server.
  • An endpoint enrollment account is essentially a set of API credentials that is not inherently tied to any particular server or device.
  • Setting up endpoint enrollment accounts is a one-time action that does not require annual renewal.
  • If account information is lost or needs to be replaced, contact incommon-certificate-service@umich.edu for assistance.
  1. If your request is approved, the ITS Web Hosting Team will provide ACME credentials for your endpoint enrollment account(s) that you can retrieve via U-M Dropbox.

Configure ACME client software

  1. Select the ACME client software you want to use. The ITS Web Hosting Team can provide support with two ACME client software options: certbot and win-ACME.
  2. To install and configure either of the two options, refer to the client software website for the full end-to-end instructions, with the addition of following the UM-specific instructions/exceptions.

Certbot and UM-specific instructions

These steps apply to prepping Linux based systems for Certbot:

  • An Incommon enrollment account with ACME credentials is required BEFORE setting up a Certbot client (see above Enrollment process).
  • Apache (Other web server types can also be used)
    • Configure Firewalls for Site Binding.
      • Open port 80 and 443 to the public.
      • Modify Linux and network FW to allow Certbot clients.
  • Follow the Certbot Instructions.
    • Request a certificate.
      • An Endpoint Enrollment account with ACME Credentials will be required at this point.
      • Using your Certbot client, you send the EAB values (KeyID and HMAC Key) along with other certificate-related information to the enrollment endpoint (ACME server). The ACME server checks the EAB values and links the accounts.

win-ACME and UM-specific instructions

These steps apply to prepping Windows based systems for win-ACME:

  • An Incommon enrollment account with ACME credentials is required BEFORE setting up a win-ACME client (see above Enrollment process). Otherwise the clients will use Let's Encrypt, which is the default in the win-ACME Instructions.
  • IIS
    • Configure Site Binding.
    • Open port 80 to the public.
    • Modify Windows FW to allow ACME Client. ​
  • Follow the win-ACME instructions.
    • Request a certificate.
      • An Endpoint Enrollment account with ACME Credentials will be required at this point.
      • Using your ACME client, you send the EAB values (KeyID and HMAC Key) along with other certificate-related information to the enrollment endpoint (ACME server). The ACME server checks the EAB values and links the accounts.
    • Use the menu within ACME interface to manage renewals and configure advanced settings.

For additional information

  • For an overview of the ACME protocol, visit the Sectigo website.
  • You may choose to use any of the available ACME client software options. For a list of links to other ACME client software options, visit the Let’s Encrypt website.

How It Works

This diagram shows the end-to-end process of using ACME to automate the renewals of InCommon certificates. Steps 1-2 in the diagram are the Getting Started steps above.

Diagram that shows the end-to-end process of using ACME to automate the renewals of InCommon certificates

For the initial certificate and each time the certificate is renewed, the ACME client fully performs step 3 in this diagram automatically. This process is expedited because Domain Control Validation is skipped for certificates under umich.edu and any other pre-verified domains.

The actions performed by the ACME client in step 3 are:

3a. The ACME client contacts the Sectigo ACME server to request the certificates.

  • This may happen multiple times (and at different times) on different devices.
  • For each DNS FQDN requested in each certificate that falls under a domain authorized in the customer’s ICM ACME account, the Sectigo ACME server issues a challenge to your device to verify that the device requesting the certificate is already in control of that domain name.
    • Currently, only HTTP and DNS challenges are permitted (email based challenges are not permitted).
    • FQDNs that cannot be verified are dropped from the list of names to issue in the certificate(s).
  • Sectigo may automatically issue certificates for domains that have been previously verified by Sectigo if the ACME account is authorized for those domains without performing additional DCV for the names in the certificate signing request.

3b. The Sectigo ACME server issues the certificate(s) for the names that were successfully verified.

3c. The ACME client running on the customer’s device retrieves and optionally installs the issued certificate(s).

  • Unless the customer chooses to not set this up, then at a predetermined point before certificate(s) expire, the ACME client will repeat step 3, retrying as necessary until the certificate either gets renewed or expires.
Last Updated: 
Thursday, May 5, 2022