Skip to main content

Automation examples with third-party ACME clients

With CertCentral, you can automate certificates using any third-party ACME client. One such client is EFF's Certbot.

The examples here demonstrate use of the Certbot client to initiate certificate automation actions for the Apache web server.

Although these examples use Certbot, please note that DigiCert supports any ACME client or web server.

Notice

For instructions on how to use Kubernetes cert-manager to create and manage TLS/SSL certificates, see  Configure cert-manager and DigiCert ACME service with Kubernetes.

Before you begin

  • Make sure you have enabled automatic certificate request approvals for your CertCentral account and prevalidated the organization and domains for which will use ACME to request immediate issuance of OV/EV certificates.

  • Make sure you have installed and configured your preferred ACME client following the software provider's guidelines.

  • Set up an ACME Directory URL for your preferred ACME client in CertCentral.

  • Root privileges required to install certificates for the web server.

Warning

CertCentral handles all validation checks itself, independent of the ACME protocol. The FQDN must be prevalidated in the CertCentral platform and be active and within the validation reuse period.

During an ACME automation event, no authorization is performed by the ACME protocol itself even though requested. All authorization checks are performed out of band by CertCentral's enterprise registration authority (RA) services.

Certbot: Issue and install a certificate

If you installed the certbot-auto script, replace certbot with ./certbot-auto in the command. You might need to specify the path of certbot-auto if it's not added to your server's PATH configuration.

  1. Open a terminal session on your web server, for example using SSH.

  2. At the terminal prompt, request a certificate using Certbot and the command syntax below:

    • Make sure to replace YOUR-KEY-IDENTIFIER with the external account binding KID.

    • Make sure to replace YOUR-HMAC-KEY with the external account binding HMAC key.

    • Make sure to replace YOUR-ACME-URL with the ACME Directory URL created previously.

    • Make sure to replace FQDN with the fully-qualified domain name you want the certificate to secure. For each FQDN, add an additional -d option.

      sudo certbot --apache --register-unsafely-without-email --eab-kid=YOUR-KEY-IDENTIFIER --eab-hmac-key=YOUR-HMAC-KEY --server “YOUR-ACME-URL” -d FQDN

      Example:

      sudo certbot --apache --register-unsafely-without-email --eab-kid=zcwmKf9sCnDUZsbCOgnv1ijy46l6UeEYCavSQQirl-g --eab-hmac-key=RHZraHBXQUxWTEFGdFhndjRVNmV3S3F6c2VNZDM1QzRURGhjdHF3S1NublJjN3dhVUFObzA0SXJwVHBnU2xnRA --server “https://acme.digicert.com/v2/acme/directory/” -d digicert.com -d www.digicert.com

  3. Enter your Certbot command, customized as needed.

    For additional information about the commands and options used in these instructions, see Certbot: ACME automation options.

  4. You will be asked to accept the Terms of Service. Type "A” and press enter.

    Currently, DigiCert doesn't have any additional Terms of Service for the ACME.

    If your request includes an FQDN that Cerbot can't find a matching virtual host for, you'll be prompted to select the virtual host you want to install the certificate on. On Apache, check the Virtual Directory listing for ServerName to match the FQDN.

  5. Select whether to redirect HTTP traffic to HTTPS.

    Choosing to redirect disables HTTP access to your website.

  6. When finished, your server displays a success message: “Congratulations! You have successfully enabled your domains…”

Your ACME certificate request is complete and the newly issued certificate is installed on your web server. Visit your website to confirm your certificate is in place.

Notice

ACME error codes: ACME returns the same errors and error messages as those returned in the CertCentral API. For a list of error codes and what they mean, see Errors.

Certbot: Renew and reissue a certificate

Renew a certificate when it has expired or is due for renewal. Reissue a certificate when it is missing or has been revoked.

To renew and reissue, use this Certbot command syntax:

sudo certbot --apache --register-unsafely-without-email --eab-kid=YOUR-KEY-IDENTIFIER --eab-hmac-key=YOUR-HMAC-KEY --server “YOUR-ACME-URL” -d FQDN

Append the orderId and the action to the URL, as shown below.

Example (renew):

sudo certbot --apache --register-unsafely-without-email --eab-kid=zcwmKf9sCnDUZsbCOgnv1ijy46l6UeEYCavSQQirl-g --eab-hmac-key=RHZraHBXQUxWTEFGdFhndjRVNmV3S3F6c2VNZDM1QzRURGhjdHF3S1NublJjN3dhVUFObzA0SXJwVHBnU2xnRA --server “https://acme.digicert.com/v2/acme/directory/?orderId=57718329&action=renew” -d digicert.com -d www.digicert.com

Example (reissue):

sudo certbot --apache --register-unsafely-without-email --eab-kid=zcwmKf9sCnDUZsbCOgnv1ijy46l6UeEYCavSQQirl-g --eab-hmac-key=RHZraHBXQUxWTEFGdFhndjRVNmV3S3F6c2VNZDM1QzRURGhjdHF3S1NublJjN3dhVUFObzA0SXJwVHBnU2xnRA --server “https://acme.digicert.com/v2/acme/directory/?orderId=57718329&action=reissue” -d digicert.com -d www.digicert.com

Note

For Multi-year plan accounts:

  • Renew a certificate when the order coverage is expiring.

  • Reissue a certificate if it has been revoked or is expiring within the order coverage.

Certbot: Issue a duplicate certificate

To increase security and simplify installation of the certificate across multiple servers, issue a duplicate certificate for each server.

The details in the duplicate certificate will be the same as in the original certificate. Duplicate certificates never require DigiCert to revoke previous copies of your certificate.

To issue a duplicate certificate, use this Certbot command syntax:

sudo certbot --apache --register-unsafely-without-email --eab-kid=YOUR-KEY-IDENTIFIER --eab-hmac-key=YOUR-HMAC-KEY --server “YOUR-ACME-URL” -d FQDN

Append the orderId and the action to the URL, as shown below.

Example:

sudo certbot --apache --register-unsafely-without-email --eab-kid=zcwmKf9sCnDUZsbCOgnv1ijy46l6UeEYCavSQQirl-g --eab-hmac-key=RHZraHBXQUxWTEFGdFhndjRVNmV3S3F6c2VNZDM1QzRURGhjdHF3S1NublJjN3dhVUFObzA0SXJwVHBnU2xnRA --server “https://acme.digicert.com/v2/acme/directory/?orderId=57718329&action=duplicate” -d digicert.com -d www.digicert.com

Certbot: ACME automation options

  • certbot: runs the Certbot executable.

  • certbot-auto: Use this in place of certbot when the certbot-auto script is installed. You might need to specify the path of certbot-auto if it's not added to your server's PATH configuration.

  • --apache: Specifies the Apache Certbot plugin that will install the certificate for you. Optional.

  • --register-unsafely-without-email: Allows you to skip creating an ACME account. Because your request is already connected to your CertCentral account, this is not needed. Optional.

  • --server “ URL ”: Specifies what ACME server should fulfill your request. Place your ACME Directory URL in double quotations after this option.

  • --eab-kid=YOURKID: Specifies the key identifier, which is a part of the common URL.

  • --eab-hmac-key=YOURHMACKEY: Specifies the key used for signing the response.

  • -d YOUR DOMAIN: The fully-qualified domain name included in the certificate. For each FQDN in the certificate, include a –d YOURDOMAIN. If you don't include this option, Certbot will prompt you about the domains you want to include based on your configured virtual hosts. Optional.

  • orderId “YOURORDERID”: Specifies the order ID type of the existing certificate.

  • action “YOURACTION”: Specifies the action on the certificate being requested.

A full list of Certbot commands is available through the terminal with certbot –help or see the list of commands on the Certbot documentation website.

What's next?

Your ACME certificate request is complete and the newly issued certificate is installed on your web server. Visit your website to confirm your certificate is in place.

You can reuse your ACME Directory URL to make additional certificate requests for the same certificate product and prevalidated organization.

To request certificates for a different product or organization, create a new unique ACME Directory URL for that product or organization. See Use a third-party ACME client for host automations.

In this section: