Let’s Encrypt Wildcard Certificates: DNS-01 Validation, Setup Steps, and Safe Renewal Workflows

Overview

A Let’s Encrypt wildcard certificate uses an ACME DNS-01 challenge to prove control of a domain. During issuance, the ACME client asks you to publish a temporary value in a TXT record beneath _acme-challenge. After the certificate authority can retrieve the expected value from DNS, it can issue the certificate.

A certificate for *.example.com can cover names such as app.example.com, api.example.com, and www.example.com. It does not normally cover the bare domain example.com, and it does not extend to deeper names such as dev.app.example.com. If both the apex domain and its subdomains need HTTPS, request the apex name and wildcard name together, or use a certificate strategy that matches the names you actually operate.

Wildcard certificates are useful when subdomains are numerous, created dynamically, or distributed across several services. They are not automatically the best choice. A certificate containing only the specific hostnames can reduce the impact of a private-key compromise and may be easier to operate when the list of names is small and stable. Review the certificate scope, server layout, and trust boundaries before choosing.

For a broader explanation of single-domain, SAN, and wildcard approaches, see Let’s Encrypt for Subdomains: Single-Domain, SAN, and Wildcard Strategies Compared. If you need the mechanics of TXT records in more detail, use the DNS-01 Challenge Guide.

Checklist by scenario

Scenario 1: Manual DNS validation for an occasional certificate

1. Confirm the names you need. For example, decide whether the request should include example.com, *.example.com, or both.
2. Confirm that you can edit authoritative DNS for the domain. Editing records at a hosting provider is not sufficient if the domain’s nameservers point elsewhere.
3. Run your ACME client and copy the requested TXT name and value exactly. The name will usually be under _acme-challenge.example.com.
4. Create the TXT record without adding quotation marks unless your DNS interface specifically requires them. Do not replace existing TXT values: multiple validation values may need to coexist.
5. Check the record from an independent DNS lookup service or with a command such as dig TXT _acme-challenge.example.com. Wait for the authoritative answer rather than relying only on a local resolver cache.
6. Complete validation, then remove obsolete challenge records when your client no longer needs them. Keep records required by other active challenges.
7. Install the resulting certificate and private key on every intended TLS endpoint. Test the wildcard hostnames individually; a certificate being valid does not guarantee that every service is configured to use it.

Scenario 2: Automated DNS with a provider API

1. Choose an ACME client or DNS plugin that supports your DNS provider. Follow that tool’s current documentation rather than copying commands designed for a different client.
2. Create a dedicated API credential with the narrowest permissions available. For a Cloudflare DNS setup, prefer a scoped token limited to the relevant zone and DNS record changes instead of a broad account credential.
3. Store the credential outside the web root and source code. Use a protected environment file, secret store, or operating-system credential mechanism, and restrict read permissions to the renewal process.
4. Configure the client to create and remove the _acme-challenge TXT record. Confirm that it can address the authoritative zone when your DNS is split across a registrar, DNS host, CDN, or managed platform.
5. Run a renewal simulation or staging test where supported. Check both the ACME client output and the DNS provider’s audit trail.
6. Install a post-renewal hook that reloads the web server or proxy only after a successful certificate update. Then test the hook independently so a valid renewal does not leave the service using an older certificate.
7. Monitor renewal success and certificate expiry. Automation without an alert or periodic test can fail silently after an API change, permission edit, DNS migration, or server replacement.

For server-side installation examples, see the Certbot setup guide for Nginx and Apache. The separate guide to automating Let’s Encrypt renewal covers timers, scheduled jobs, and monitoring considerations.

Scenario 3: Delegating validation to a separate DNS zone

If the production DNS account should not be allowed to modify the main zone, consider delegating _acme-challenge to a controlled validation zone. This can be done with appropriate CNAME or NS records, but the exact design depends on your DNS provider and ACME client. Document the delegation, test that the client follows it, and ensure the delegated account cannot alter unrelated production records. This arrangement can separate certificate automation from application DNS, but it adds records and ownership details that must be maintained.

What to double-check

• Authoritative nameservers: Use DNS queries to identify which servers are authoritative. A TXT record entered at the registrar may have no effect if the zone is hosted by Cloudflare or another provider.
• Record name formatting: Some control panels expect only _acme-challenge; others expect the fully qualified name. Follow the panel’s convention and verify the published result.
• Existing TXT records: Do not delete SPF, verification, or another ACME client’s TXT value. Multiple TXT records at the same owner name are valid when each value is preserved.
• CAA policy: If CAA records exist, confirm that they permit the certificate authority you intend to use. A restrictive CAA policy can block issuance even when the TXT record is correct. See the CAA records guide.
• DNS provider permissions: A credential that can edit every zone is difficult to justify for a single certificate workflow. Use zone-specific and record-specific controls where the provider supports them.
• Private-key distribution: A wildcard private key may be installed on multiple servers. Track where it exists, limit access, and have a replacement plan if one host is compromised.
• Renewal behavior: Renewal must update every endpoint that serves the certificate. A load balancer, reverse proxy, container image, and origin server may each have separate certificate paths.

Common mistakes

Using HTTP-01 for a wildcard request: Wildcard validation requires DNS-01. If the server is private, behind a firewall, or not yet deployed, DNS-01 can also be useful for ordinary hostnames, but it still requires control of authoritative DNS.

Assuming DNS changes are immediate: Recursive resolvers cache records according to TTL and may not show a new value at once. Query authoritative servers when troubleshooting, then allow for resolver caching before retrying.

Leaving a global DNS API key on a server: If the host is compromised, broad credentials can expose unrelated domains. Replace broad credentials with a narrowly scoped token, protect its file permissions, and rotate it after staff, host, or workflow changes.

Issuing only the wildcard name: *.example.com does not usually cover example.com. Include both names when the apex site also needs HTTPS.

Forgetting the renewal hook: A renewed file on disk is not necessarily the certificate currently served. Check the live endpoint after renewal and reload the relevant service when required.

Testing only one subdomain: Verify representative services, including those behind different load balancers, CDNs, or ingress controllers. A shared wildcard certificate can hide configuration differences between hosts.

When to revisit

Review this checklist before a seasonal planning cycle, a planned traffic increase, or any migration involving DNS, hosting, a CDN, or a certificate-management tool. Also revisit it whenever subdomain ownership changes, a new environment is added, or a wildcard private key must be copied to another endpoint.

At minimum, schedule a recurring operational review of the renewal job, API token permissions, DNS delegation, certificate coverage, and alerting. Perform a controlled renewal test after changing the ACME client, DNS provider, server image, container deployment, or credential store. Keep a short record of the certificate names, DNS zone owner, renewal command, secret location, installation paths, reload hook, and responsible team. That documentation turns a future failure into a repairable checklist rather than an investigation.

When a renewal or validation fails, capture the exact ACME error and inspect DNS from outside the application host. Compare the requested TXT value with the authoritative response, then check CAA, permissions, and propagation. The HTTPS troubleshooting checklist and ACME error-code guide can help organize that diagnosis. Once the workflow succeeds, confirm the live certificate and document the change.