SSL
How do ACME domain validation challenges work?
Short answer
ACME clients prove control of a domain by completing a challenge, such as serving a token at a particular HTTP path or creating a DNS TXT record. The certificate authority then issues the certificate if validation succeeds.
What changes the answer
- HTTP-01 versus DNS-01 challenge type
- Wildcard certificates need DNS validation
- Port 80 reachability and redirects
The idea
ACME is the protocol that Let's Encrypt and some other certificate authorities use to issue certificates automatically. A certificate authority should issue a certificate for a name only to someone who controls it. The ACME client on your server asks for a certificate, receives a challenge, completes it, and the authority checks the result before issuing.
The two common challenge types
With HTTP-01, the client places a token at a well-known path under /.well-known/acme-challenge/ and the authority fetches it over plain HTTP on port 80. Let's Encrypt documents that its implementation follows redirects, so a redirect can change where the check ends up. With DNS-01, the client publishes a TXT record under _acme-challenge for the name, and the authority looks it up in DNS. Let's Encrypt documents that wildcard certificates require DNS-01.
Which to choose
HTTP-01 is simple when the domain already points to a server that can serve port 80 and you only need certificates for specific hostnames. DNS-01 suits wildcards and servers that are not reachable from the internet, but it needs a way for the client to update DNS, usually through your DNS provider's API. Treat API credentials with care and give them the least access the provider allows.
When validation fails
- The name does not resolve to the server running the client.
- A firewall, security group or provider rule blocks port 80 for HTTP-01.
- A redirect sends the check somewhere unexpected.
- For DNS-01, the TXT record was not created or has not been seen yet because of caching.
Before you rely on renewals
Certificates are renewed regularly, so test that renewal works rather than only issuance. After DNS or hosting changes, check that the challenge still reaches the right place. The troubleshooting checklist can help you record what you see.
Practice safely
Certificate authorities limit how many requests you can make in a period. Let's Encrypt publishes its rate limits and provides a separate staging environment for testing, so use that while you experiment rather than repeatedly requesting production certificates. Check its documentation for the current limits before automating issuance.