Use the ACME protocol with the PKI plugin

The Automatic Certificate Management Environment (ACME) protocol is an IETF standardized protocol, RFC 8555, that lets you automate the way clients prove control over a domain name and request a leaf certificate from an ACME certificate authority (CA). The protocol defines multiple challenge types, but the most commonly used types are HTTP-01, DNS-01, and TLS-ALPN-01.

The ACME client provisions a specific resource on the domain it wants a certificate for based on the challenge type. For example, a client would provision a specific HTTP endpoint for HTTP-01 or a specific DNS record for DNS-01. Once the client successfully proves control over the domain, it can request a certificate issuance from the ACME CA.

Vault PKI ACME directories

Vault PKI supports multiple ACME directories. Each directory has different restrictions around configuration defaults, issuers, and roles. By default, the PKI plugin uses the value of default_directory_policy for the ACME directory. The following table provides the default issuer, role, and directory URL values for the currently supported directories:

If you do not set an explicit role, Vault uses the default_directory_policy value in the ACME configuration to determine the appropriate behavior:

• forbid - Makes the directory forbidden.

• sign-verbatim - Similar to calling Sign Verbatim with additional owner verification baked into the ACME protocol for the requested certificate identifiers. Clients receive certificates for any identifier where they can prove ownership.

• role:role_ref - Enforce ACME challenge validation and use the specified role to restrict the certificate. The client receives a certificate if they can prove ownership of the requested identifiers and the identifiers are allowed by the role.

• external-policy - Enforce ACME challenge validation, but use the Certificate Issuance External Policy Service (CIEPS) to validate and template the certificate instead of a role. You can specify an explicit policy name with external-policy:policy.

  Enterprise

ACME external account bindings

ACME External Account Binding (EAB) Policy can enforce that clients need to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client fetches a new EAB token. This returns two values: a key identifier You can use ACME External Account Binding (EAB) Policy to force clients to have a valid external account binding to Vault. Before registering a new account, an authenticated Vault client fetches a new EAB token, which provides a key identifier and an HMAC key used by the ACME client to authenticate with EAB.

For example:

1. Create the EAB token in Vault:

   $ vault write -f /pki/acme/new-eab
   

2. Use the key ID and HMAC to call the ACME directory. For example, to use the EAB policy with Certbot:

   $ certbot certonly \
       --server https://localhost:8200/v1/pki/acme/directory \
       --eab-kid <id>                                        \
       --eab-hmac-key <hmac-key>
   

With or without EAB, requests from the ACME client do not use traditional Vault authentication. Instead, the requests authenticate through the ACME protocol.

With EAB, a Vault authenticated client first fetches an EAB token then passes it to the ACME client for use on the initial registration. The EAB token binds the ACME client registration to an authenticated Vault endpoint without binding to the client entity or other information.

We strongly recommend enabling EAB for public-facing Vault
deployments. Use the `VAULT_DISABLE_PUBLIC_ACME` environment
variable to force-enable EAB for all ACME instances.

Enable ACME support on a Vault PKI mount

Step 1: Update tunable parameters on your PKI mount

You must tune the allowed_response_headers setting on your PKI mount configuration to provide the following response headers expected by ACME clients in responses from the PKI ACME server:

• Link
• Location
• Replay-Nonce

For example, to tune allowed-response-headers for a PKI plugin mounted at pki/:

$ vault secrets tune
    -allowed-response-headers=Link \
    -allowed-response-headers=Location \
    -allowed-response-headers=Replay-Nonce \
    pki/

Step 2: Update your PKI ACME configuration

1. Update your cluster path configuration for the PKI mount. The cluster path supplies the ACME base URL to clients from the ACME directory:

   $ vault write pki/config/cluster path=https://cluster-b.vault.example.com/v1/pki
   

2. Update your ACME configuration to set the default behavior of the top level ACME directory, restrict ACME to certain issuers and roles, and define the EAB policy (if applicable). For example, to specify a restrictive EAB policy along with the allowed roles:

   $ vault write pki/config/acme \
      enabled=true \
      default_directory_policy="role:role-acme-a" \
      eab_policy="always-required" \
      allowed_roles="role-acme-a,role-acme-b"
   

Additional resources

• The Enable ACME with PKI secrets engine tutorial walks you through the process of enabling ACME support on a PKI secrets engine mount and using it with the Caddy ACME client.
• The ACME troubleshooting guide provides a list of advice for troubleshooting failures with ACME issuance and Vault PKI.
• The PKI secrets engine API reference provides additional details for interacting with the PKI plugin.