Skip to main content
Video tutorial · 1:28

Custom ACME CAs

A custom ACME CA is an ACME server of your own choosing, added to a project beside the public catalog: an internal step-ca, EJBCA or HashiCorp Vault PKI, or a commercial CA's ACME endpoint that is not in the list. Once added, you create ACME accounts on it and issue, renew and revoke exactly as with a public CA.

Custom ACME CAs are project-scoped, like ACME accounts and AD CS connections. Adding, editing, testing and deleting one needs the project Admin role; viewers see them. They can be granted per resource (resource grants, type Custom ACME CAs).

What the CA must support​

  • An RFC 8555 directory over HTTPS (newNonce, newAccount, newOrder — Test checks these three).
  • DNS-01 for automated validation through a DNS provider, or manual DNS. HTTP-01 works when the CA can reach CertAutoPilot's challenge path (HTTP-01).
  • Revocation (revokeCert) if you want to revoke from CertAutoPilot.
  • ARI (renewal information, RFC 9773) is optional. Without it certificates renew on their renewal threshold; Test tells you which applies.

Add the CA​

Settings → Certificate Authorities → Custom ACME CAs → Add ACME CA.

FieldPurpose
NameUnique within the project.
Directory URLThe ACME directory, for example https://ca.example.com/acme/acme/directory. https only, no user name, query or fragment. It cannot be changed while accounts exist on the CA — they are registered at that address; add a new CA instead.
CA certificatePEM of the CA that issued the directory's HTTPS certificate — one or more certificates. It is added to the system's trusted roots, for this CA's accounts only; other CAs are not affected. Leave it empty when the directory has a publicly trusted certificate.
Requires EABEvery account on the CA must be created with External Account Binding credentials (see below).
Validation typeDV, OV or EV, recorded on each account. OV and EV put the organization in the certificate request.
Allow private networkLets the directory point at a private or loopback address (10.x, 192.168.x, 127.0.0.1, …) — where a self-hosted CA usually lives. Without it, a directory URL written as a private IP address (or localhost) is refused at save; a host NAME that resolves to a private address is accepted at save and refused when CertAutoPilot connects (Test, registration, every issuance). Link-local and cloud-metadata addresses are refused regardless. Turning it on is logged as a warning.

Then press Test. It reads the directory with exactly the connection the CA's accounts will use — same trust, same network rule — and shows whether the CA requires EAB, whether it offers ARI and the certificate profiles it lists. Nothing is registered at the CA. The result is shown as the CA's status (Reachable / Test failed, with the reason).

Create an account on it​

ACME Accounts → Add Account, pick the CA under Custom ACME CAs (this project), enter a name and a contact e-mail. The environment field does not apply and is hidden. CertAutoPilot registers the account at the CA right away; a refusal is shown in the CA's own words.

A CA can hold several accounts. In lists the account's CA is shown by the custom CA's name.

External Account Binding​

If the CA needs EAB, its operator gives you a key ID and an HMAC key (base64url). With Requires EAB on, the account form asks for both and refuses to continue without them. If the CA requires EAB and the record does not say so, the registration is refused by the CA (externalAccountRequired) — Test warns about this case.

Editing a CA​

  • A new CA certificate or a change of Allow private network applies to every account on the CA at once, including issuances and revocations that run afterwards. Removing the CA certificate makes a privately-rooted CA untrusted again.
  • Turning Allow private network off is refused while the directory URL is a private IP address; with a host name the refusal comes at the next connection.
  • A rename to a name another CA of the project already uses is refused (422). A Test still running while the directory URL changes does not mark the new URL as tested.
  • A changed directory URL (allowed only while the CA has no accounts) resets the status to Not tested.

A CA with accounts cannot be deleted; delete its accounts first (an account with certificates cannot be deleted either).

Example: step-ca​

  1. On the step-ca host, add an ACME provisioner: step ca provisioner add acme --type ACME, then restart step-ca. Its directory is https://<host>:<port>/acme/acme/directory.
  2. Copy step-ca's root: step ca root root_ca.crt (or $(step path)/certs/root_ca.crt).
  3. Add the CA with that directory URL, paste the root into CA certificate, and turn on Allow private network if the host has a private address. Test.
  4. For DNS-01, step-ca must be able to see the challenge record: its own resolver (or --resolver <ip:port>) has to answer for your zones.
  5. Add an account and issue.

step-ca's default certificate lifetime is short (24 hours); set the provisioner's defaultTLSCertDuration if you want longer, and keep the certificate's renewal threshold below the lifetime.

Troubleshooting​

"The CA's HTTPS certificate is not trusted"​

Paste the certificate of the CA that issued the directory's HTTPS certificate into CA certificate — usually the private root. Certificates only: a pasted private key is refused (the field is shown to every project member).

"The directory resolves to a private or loopback address"​

Turn on Allow private network on the CA.

"The directory URL did not answer an ACME directory"​

The URL is not the directory itself (a provisioner listing, a web page, a missing path segment). Use the full directory URL your CA documents.

Registration refused with externalAccountRequired​

Turn on Requires EAB and create the account with the key ID and HMAC key from the CA.

Multi-node installs​

Custom ACME CAs and accounts on them can be created only once every node runs a version that supports them (1.6.1 or later); until then the request is refused with CLUSTER_UPGRADE_REQUIRED.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Chain Certificates from the CCADB and a Custom ACME CAYouTube ↗