View a markdown version of this page

Issuing certificates through ACME - AWS Certificate Manager
How issuance worksExample: Issuing a certificate with CertbotACME certificates in ACMViewing ACME certificatesRevoking ACME certificatesCertificate renewal

Issuing certificates through ACME

After your PKI administrator sets up an ACME endpoint with domain validations and external account bindings, application owners can use ACME clients to issue certificates. This section describes the issuance flow, provides a brief example using Certbot, and explains how ACME-issued certificates appear in ACM.

How issuance works

The ACME certificate issuance flow follows the RFC 8555 protocol:

  1. Account registration: The ACME client registers an account using the EAB credentials (key ID and MAC key). This is a one-time step per ACME client.

  2. Certificate order: The client creates an order specifying the domain names for the certificate.

  3. Authorization: The ACME server checks pre-configured domain validations. Because the endpoint uses PRE_APPROVED authorization, no live challenges are required from the client.

  4. Finalize: The client submits a Certificate Signing Request (CSR) to finalize the order, and ACM issues the certificate.

  5. Download: The client downloads the issued certificate chain.

Important

The private key is generated by the ACME client and never leaves the client's system.

Example: Issuing a certificate with Certbot

This example shows how to register an ACME account and request a certificate using Certbot.

Prerequisites

  • An ACME endpoint in ACTIVE status (you have the directory URL)

  • At least one domain validation in VALID status for the domain you want

  • EAB credentials (key ID and MAC key) from your PKI administrator

  • Certbot installed on your system

To register an account and request a certificate

Important

Certificate issuance through the ACM ACME endpoint can take several minutes. Configure your ACME client's issuance timeout to at least 600 seconds (10 minutes) to prevent the client from timing out before the certificate is delivered. Many ACME clients default to 30-90 seconds, which is not sufficient.

Run the following command:

certbot certonly \
    --standalone \
    --non-interactive \
    --agree-tos \
    --email user@example.com \
    --server https://acm-acme-enroll.region.api.aws/00000000-0000-0000-0000-000000000000/directory \
    --eab-kid AAABBBCCC111222333 \
    --eab-hmac-key base64encodedmackey \
    --issuance-timeout 600 \
    --domain www.example.com

After successful issuance, Certbot stores the certificate and private key in its default location (typically /etc/letsencrypt/live/www.example.com/).

ACME certificates in ACM

Certificates issued through ACME automatically receive a standard ACM certificate ARN and appear in the ACM certificate inventory. However, ACME-issued certificates have important differences from certificates issued through RequestCertificate.

Key differences

  • Private key is client-side: The certificate private key is generated and stored by the ACME client. ACM does not have access to the private key.

  • Cannot bind to integrated services: Because AWS does not hold the private key, ACME certificates cannot be used with Elastic Load Balancing, CloudFront, or API Gateway.

  • Not in default list output: ACME certificates do not appear in ListCertificates results by default. You must include the CertificateKeyPairOrigins filter with value ACME to include them. SearchCertificates returns ACME certificates by default.

  • Cannot export through ACM: The ExportCertificate API cannot be used because the certificate is already exported by definition since the client has it.

  • Revocation through ACME only: Use the ACME endpoint's revoke-cert URL. The ACM RevokeCertificate API does not work for ACME-issued certificates.

  • Renewal is client-driven: ACM does not auto-renew ACME certificates. The ACME client must request a new certificate before the existing one expires.

Viewing ACME certificates

In the ACM console, use the filter to include certificates with an ACME key pair origin. For more information about finding certificates, see Search certificates.

To list ACME certificates (AWS CLI)

Use list-certificates with the CertificateKeyPairOrigins filter:

aws acm list-certificates \
    --certificate-key-pair-origins ACME

To search for ACME certificates (AWS CLI)

Use search-certificates with the CertificateKeyPairOrigin filter to find ACME certificates by additional criteria:

aws acm search-certificates \
    --filter-statement '{"Filter": {"AcmCertificateMetadataFilter": {"CertificateKeyPairOrigin": "ACME"}}}'

You can also search for certificates issued through a specific endpoint or ACME account by filtering on AcmeEndpointArn or AcmeAccountId.

To view certificate details (AWS CLI)

Run the following command:

aws acm describe-certificate \
    --certificate-arn arn:aws:acm:region:account-id:certificate/certificate-id

Revoking ACME certificates

To revoke a certificate issued through ACME, use the ACME protocol's revoke-cert endpoint. The ACME client handles this.

Note

ACME-issued certificates cannot be revoked using the ACM RevokeCertificate API. You must revoke these certificates through the ACME endpoint that issued them.

The following example shows revocation using Certbot:

certbot revoke \
    --cert-path /etc/letsencrypt/live/www.example.com/cert.pem \
    --server https://acm-acme-enroll.region.api.aws/00000000-0000-0000-0000-000000000000/directory

The revocation is authorized by the IAM role associated with the client's external account binding, so the same IAM policies and SCPs that apply to the standard acm:RevokeCertificate action apply here. For more information about the required IAM role configuration, see IAM for ACME certificate automation.

Certificate renewal

ACME certificates are not renewed by ACM. Your ACME client is responsible for requesting a new certificate before the current one expires. Most ACME clients (including Certbot) support automatic renewal through scheduled tasks (such as cron jobs or systemd timers).

ARN stability across renewals

When an ACME client renews a certificate, ACM determines whether the new issuance is a renewal of an existing certificate or a distinct certificate. If the issuance comes from the same ACME account with the same certificate metadata (such as domain names and key algorithm), ACM updates the existing certificate ARN rather than creating a new one. This keeps the ARN stable across renewals, which simplifies tracking and automation.

If the original certificate has been removed from ACM (for example, because it expired more than one year ago and was automatically deleted), a subsequent issuance with the same metadata creates a new certificate ARN.

Certbot auto-renewal example (typically configured automatically during Certbot installation):

certbot renew --quiet