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.

Watch ACME Protocol Orientation Session (53:39) for a demonstration of installing, configuring, and using the Certbot ACME client to obtain InCommon certificates.

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
University-wide support contract Yes 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 [email protected] 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

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).  Otherwise, the clients will use Let's Encrypt, which is the default for Certbot and which requires different configuration.
  • Install Certbot by following the standard Certbot instructions for your operating system and web server.
  • Make sure you have your InCommon Certificate Service credentials in the Certbot configuration file.  On most Linux servers, the configuration file is /etc/letsencrypt/cli.ini   Change the values of email, server, eab-kid, and eab-hmac-key below to be correct for your InCommon ACME endpoint enrollment account.  
    email = [email protected]
server = the-ACME-URL-you-received-when-enrolling
eab-kid = xxxxxxxxxx
eab-hmac-key = yyyyyyyyyyyyyyyyyyyy
  • Request a certificate (replace example.umich.edu with the domain(s) you want the certificate to be valid for): 
    certbot certonly --standalone --non-interactive --agree-tos --domains example.umich.edu

Win-ACME

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 for Win-ACME and which requires different configuration.
  • Configure the IIS Site Bindings
  • Ensure port 80 is open to the public (although InCommon ACME should not need to perform DCV)
  • Modify the Windows firewall to allow Win-ACME client traffic
  • Install Win-ACME:
    • Option 1:
      • Download the .zip file from the download menu
      • Unpack the .zip file to a location on your hard disk
      • Run wacs.exe
    • Option 2:
      • Install .NET Core
      • Run dotnet tool install win-acme --global 
      • Run wacs.exe
  • Request a certificate.
    • Run the following command, replacing uuuuuuuuuuuuuuuu with the ACME URL you received when enrolling, [email protected] with your team's email address, xxxxxxxxxx with your ACME EAB Key ID, and yyyyyyyyyyyyyyyyyyyy with your secret ACME EAB HMAC key. 
      wacs.exe --baseuri uuuuuuuuuuuuuuuu --verbose --accepttos --emailaddress [email protected] --eab-key-identifier xxxxxxxxxx --eab-key yyyyyyyyyyyyyyyyyyyy
    • Run wacs.exe
      • Choose N: Create new certificate (simple for IIS)
    • Use the menu within the 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.
Tags: 
Web Hosting
Last Updated: 
Thursday, May 5, 2022