ACME: automate certificate issuance
Let machines request and renew their own certificates with the ACME protocol and step-ca.
ACME (Automated Certificate Management Environment) is the protocol behind Let’s Encrypt. A client proves it controls a name, and the CA issues a certificate automatically. step-ca can act as your own private ACME server.
In earlier modules you typed a provisioner password for every certificate. That doesn’t scale to hundreds of servers. With ACME, the proof is “I control this name”, and the client does all the work.
How ACME works
Section titled “How ACME works”ACME is defined in RFC 8555. It’s a short conversation over HTTPS:
- Account. The client makes an account key pair and registers it. Every later request is signed with that key, so the CA knows it’s the same client.
- Order. The client asks for a certificate for one or more names.
- Authorization and challenges. For each name, the CA offers ways to prove control. The client picks one.
- Validation. The CA checks the proof from the outside.
- Finalize. The client sends a CSR with a fresh key. The CA signs it.
- Download. The client fetches the certificate and chain.
The challenge types
Section titled “The challenge types”| Challenge | How the CA checks | Good for |
|---|---|---|
http-01 |
Fetches http://<name>/.well-known/acme-challenge/<token> on port 80. |
Web servers the CA can reach. |
dns-01 |
Looks up a TXT record at _acme-challenge.<name>. |
Wildcards, and hosts with no open port. |
tls-alpn-01 |
Connects to port 443 and checks a special certificate. | Servers that only expose 443. |
The token alone isn’t enough. The client must answer with a key authorization: the token joined to a hash of its account key. Someone who sees the token can’t answer for you.
1. Add an ACME provisioner
Section titled “1. Add an ACME provisioner”ACME clients don’t have provisioner passwords, so step-ca needs a provisioner of type ACME:
step ca provisioner add acme --type ACME✔ CA Configuration: /home/ubuntu/.step/config/ca.json
Success! Your `step-ca` config has been updated. To pick up the new configuration SIGHUP (kill -1 <pid>) or restart the step-ca process.Reload the CA:
pkill -HUP -x step-ca2. Look at the directory
Section titled “2. Look at the directory”Every ACME server publishes a directory. It’s how a client finds everything else. The URL has the form /acme/<provisioner-name>/directory:
curl -s --cacert $(step path)/certs/root_ca.crt \ https://localhost:9000/acme/acme/directory{"newNonce":"https://localhost:9000/acme/acme/new-nonce","newAccount":"https://localhost:9000/acme/acme/new-account","newOrder":"https://localhost:9000/acme/acme/new-order","revokeCert":"https://localhost:9000/acme/acme/revoke-cert","keyChange":"https://localhost:9000/acme/acme/key-change"}That’s the whole API surface. Notice there’s no “log in” endpoint. Trust comes from signatures, not sessions.
3. Get a certificate with certbot
Section titled “3. Get a certificate with certbot”certbot is the EFF’s ACME client. It works with any ACME server, not just Let’s Encrypt.
The lab VM already has it, from the Snap Store. On a host install, install it the same way:
sudo snap install --classic certbotThe snap tracks current certbot releases. Ubuntu’s apt package is an older 2.x. On macOS, use brew install certbot.
Request a certificate for localhost. certbot’s --standalone mode answers the http-01 challenge with its own small web server on port 80, so it needs sudo:
sudo REQUESTS_CA_BUNDLE=$(step path)/certs/root_ca.crt \ certbot certonly --standalone \ --server https://localhost:9000/acme/acme/directory \ -d localhost \ --register-unsafely-without-email --agree-tosREQUESTS_CA_BUNDLE tells certbot to trust your root when it talks to step-ca. Your shell expands $(step path) before sudo runs, so root uses your CA files.
Saving debug log to /var/log/letsencrypt/letsencrypt.logAccount registered.Requesting a certificate for localhost
Successfully received certificate.Certificate is saved at: /etc/letsencrypt/live/localhost/fullchain.pemKey is saved at: /etc/letsencrypt/live/localhost/privkey.pemThis certificate expires on 2026-11-17.These files will be updated when the certificate renews....No password was typed. certbot proved it controls localhost by answering on port 80.
4. Watch the conversation
Section titled “4. Watch the conversation”Look at your step-ca terminal. Each ACME step left a log line. Here are their paths, in order:
GET /acme/acme/directoryHEAD /acme/acme/new-noncePOST /acme/acme/new-accountPOST /acme/acme/new-orderPOST /acme/acme/authz/JXYImV8Mu0v9OLB0AfF82WTs2F9DSlRHPOST /acme/acme/challenge/JXYImV8Mu0v9OLB0AfF82WTs2F9DSlRH/IrPS2PfK10VxSLra6hXa8pbg2UhcAC6lPOST /acme/acme/authz/JXYImV8Mu0v9OLB0AfF82WTs2F9DSlRHPOST /acme/acme/order/KVIg8iYkMa6y7G7pvwVYUzaczjo2ldhx/finalizePOST /acme/acme/order/KVIg8iYkMa6y7G7pvwVYUzaczjo2ldhxPOST /acme/acme/certificate/tpTDFPIdXPtuA7hr3I8cLMID4cdP0DTXMatch it to the six steps above. The second authz request is certbot checking whether validation passed. The new-nonce call gets a one-time number that stops replayed requests.
5. Inspect the result
Section titled “5. Inspect the result”sudo step certificate inspect /etc/letsencrypt/live/localhost/fullchain.pem --bundle --shortX.509v3 TLS Certificate (ECDSA P-256) [Serial: 1219...8986] Subject: localhost Issuer: Lab CA Intermediate CA 2 Provisioner: acme Valid from: 2026-11-16T04:01:39Z to: 2026-11-17T04:02:39ZX.509v3 Intermediate CA Certificate (ECDSA P-256) [Serial: 1993...5668] Subject: Lab CA Intermediate CA 2 Issuer: Lab CA Root CA Valid from: 2026-11-16T04:02:18Z to: 2036-11-13T04:02:18ZThe provisioner is now acme, and the lifetime is still 24 hours. The issuer is Intermediate CA 2 because you rotated it in module 6. If you skipped that, you’ll see the original intermediate.
Look at the subject and SAN:
sudo openssl x509 -in /etc/letsencrypt/live/localhost/cert.pem -noout -subject -ext subjectAltNamesubject=X509v3 Subject Alternative Name: critical DNS:localhostThe subject is empty. Modern ACME clients put names only in the SAN. When the subject is empty, RFC 5280 says the SAN extension must be critical, and it is.
6. Renew
Section titled “6. Renew”certbot saved everything it needs in /etc/letsencrypt/renewal/localhost.conf, including your server URL. Ask it to renew:
sudo REQUESTS_CA_BUNDLE=$(step path)/certs/root_ca.crt certbot renewSaving debug log to /var/log/letsencrypt/letsencrypt.logProcessing /etc/letsencrypt/renewal/localhost.confCertificate not yet due for renewal
The following certificates are not due for renewal yet: /etc/letsencrypt/live/localhost/fullchain.pem expires on 2026-11-17 (skipped)No renewals were attempted.certbot 4.0 and later renew when a third of the lifetime is left, or half for certificates shorter than 10 days. A 24-hour certificate renews after 12 hours. Older certbot versions, like the 2.x in Ubuntu 24.04’s apt package, renew 30 days before expiry. With a 24-hour certificate, that means every run.
The certbot snap installs a timer that runs certbot renew twice a day. That’s tuned for 90-day public certificates. For 24-hour certificates, run it more often, for example every 15 minutes. On older certbot versions, also add renew_before_expiry = 8 hours to the top of /etc/letsencrypt/renewal/localhost.conf. Another option is longer ACME certificates, set with the provisioner’s --x509-default-dur flag.
Break it
Section titled “Break it”The CA can’t reach the name
Section titled “The CA can’t reach the name”Ask for a name that doesn’t point at your machine:
sudo REQUESTS_CA_BUNDLE=$(step path)/certs/root_ca.crt \ certbot certonly --standalone \ --server https://localhost:9000/acme/acme/directory \ -d nothere.example.comRequesting a certificate for nothere.example.comAll authorizations were not finalized by the CA.certbot’s summary is vague. The real reason is in /var/log/letsencrypt/letsencrypt.log:
"type":"http-01","status":"pending","token":"i3TjxPEbhNhRURTJN7hDc5HLy1VzaEPj","url":"https://localhost:9000/acme/acme/challenge/dsmAGej97IxLdrn1DPN5vKaTsCYHxcNR/1FkYe2j0nxNOKfdNoQ1bReGIsw0XccoZ","error":{"type":"urn:ietf:params:acme:error:connection","detail":"The server could not connect to validation target"}The CA tried to fetch the token from nothere.example.com and couldn’t. This is ACME working as designed. Note the error type: ACME errors are URNs from RFC 8555, so every client and server speaks the same language.
The same log shows the full challenge list step-ca offered: dns-01, http-01 and tls-alpn-01.
The client doesn’t trust your CA
Section titled “The client doesn’t trust your CA”Leave out REQUESTS_CA_BUNDLE:
sudo certbot certonly --standalone \ --server https://localhost:9000/acme/acme/directory -d localhostAn unexpected error occurred:requests.exceptions.SSLError: HTTPSConnectionPool(host='localhost', port=9000): Max retries exceeded with url: /acme/acme/directory (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1035)')))The same “unable to get local issuer certificate” you met in module 6. A private ACME server needs its root installed on every client, through REQUESTS_CA_BUNDLE, the system trust store, or step certificate install.
DNS-01 and wildcards
Section titled “DNS-01 and wildcards”http-01 can’t prove you control *.example.com. There’s no single host to fetch from. For wildcards, and for servers behind a firewall, use dns-01.
The client creates a TXT record at _acme-challenge.example.com. Its value is a hash of the key authorization. The CA looks it up, then the client deletes it.
That means your ACME client needs API access to your DNS provider. Clients such as lego and acme.sh support dozens of providers. Guard those DNS API credentials as carefully as a private key. With them, anyone can get a certificate for your domain.
Where ACME shows up next
Section titled “Where ACME shows up next”Many tools speak ACME natively. Point them at your directory URL and trust your root:
- Caddy gets and renews certificates automatically. It has an
acme_caoption. - Traefik has
certificatesResolverswith a customcaServer. - nginx has no built-in client. Pair it with certbot and
--deploy-hook "systemctl reload nginx".
Device attestation is an ACME extension too. It lets a device prove its key lives in a TPM or secure enclave before it gets a certificate.
Go deeper
Section titled “Go deeper”- RFC 8555 — the ACME protocol.
- RFC 8737 — the
tls-alpn-01challenge. - step-ca ACME documentation
- Configuring popular ACME clients for a private CA
- certbot documentation
- Let’s Encrypt: how it works
Check yourself
Tap a card to flip it. Nothing is scored or saved.
Progress is saved in this browser only.