DNS-01 ACME can prepare a certificate for a customer’s public domain before application traffic moves to the SaaS platform. It requires authorized DNS control or supported challenge delegation. A complete onboarding process also binds that hostname to the correct tenant, deploys the certificate and activates the intended application route.
This guide separates platform domain verification, CA validation, DNS updates, certificate storage and traffic cutover. It describes an architecture to operate these stages with persistent state and observable failures. Let’s Encrypt and cert-manager examples have provider-specific requirements; another CA or client may differ. Successful DNS validation alone is not proof that the correct customer application is ready to receive traffic.
Custom Domain Responsibilities in SaaS
Bind the Hostname, Certificate and Tenant
A customer may request app.example.com or the apex example.com. Within the platform, maintain an explicit verified binding between the hostname and the authorized tenant. Certificate coverage and DNS traffic routing are separate records of readiness. A wildcard for your platform domain cannot authenticate an unrelated customer hostname, and a hostname merely pointing to your edge should not automatically become claimable by any tenant.
HTTP-01 requires the requested name’s public port-80 challenge path to reach the current response. That can be arranged centrally, but may not be ready before cutover. DNS-01 can avoid this dependency when the customer authorizes a suitable DNS update path. It does not eliminate authorization work; it moves the CA proof to public DNS while the application route can remain on the existing service.
For example.com, publish the client-generated TXT response at _acme-challenge.example.com. The value is derived from the challenge and ACME account, not simply the CA’s raw token. Complete platform verification, issuance and edge deployment before requesting the application DNS change. A one-time manual TXT update is insufficient for unattended renewal unless future fresh challenges can also be completed.
Wildcard Scope and Customer Names
*.brand.yourapp.com covers one matching label below brand.yourapp.com, not the base name or deeper labels. It does not cover unrelated customer domains. For Let’s Encrypt, DNS-01 is the wildcard method among HTTP-01, DNS-01 and TLS-ALPN-01. Wildcards can reduce repeated issuance for matching names, but require continued renewal, routing and private-key protection according to their full authority.
For a planned launch, request customer authorization and prepare certificates ahead of the traffic move where possible. Keep the old service usable while cached routing can still lead to it, with any required data migration handled separately. Do not promise a fixed issuance duration: DNS publication, caches, CA processing and quotas can all delay readiness.
How DNS-01 ACME Validation Works
Separate the Token from the TXT Response
The CA supplies a challenge token. The ACME client combines it with the account-key thumbprint to form key authorization, computes its SHA-256 digest and publishes the base64url-encoded digest as the TXT value. After successful validation and the other CA requirements, it finalizes issuance. The certificate and matching private key then need a separate verified deployment to the actual TLS endpoints.
Platform verification needs a separate binding to the tenant and current hostname claim. A design can use a fresh, unpredictable tenant-specific DNS verification value with controlled expiry and reuse. This proves a form of current DNS control for that claim, not legal ownership. The CA challenge is tied to the ACME account; if the platform shares an account across tenants, that proof alone does not identify which tenant should receive the hostname.
API Capabilities and Publication Timing
Provider APIs differ in credential type and permission granularity. Verify the specific integration instead of assuming Cloudflare, Route 53 and Gandi all expose equivalent scoped tokens. Use the narrowest permissions actually supported; a dedicated validation zone may help where record-level restrictions are unavailable. Let’s Encrypt’s DNS-01 documentation explains public TXT validation and delegating challenge responses without routing application traffic first.
API success does not prove all authoritative servers now serve the value. Check publication and relevant caches with bounded polling. Preserve TXT values belonging to concurrent validations and remove only the completed operation’s value. This is especially relevant when apex and wildcard authorizations share an owner. Cleanup prevents unnecessary accumulation but cannot guarantee that the next validation will succeed.
DNSSEC and CAA Prerequisites
DNSSEC requires a valid chain through DS, DNSKEY and signatures. A stale DS or invalid signature can cause a validating recursive resolver to return SERVFAIL; missing or incorrect glue is a separate delegation/reachability problem. CAA is also independent: an applicable restrictive policy must authorize the chosen CA. The DNSSEC key rollover and DS update guide explains coordinated changes. Moving rollover to a different time alone does not repair an invalid chain.
A Persistent Certificate Workflow
Orchestration, Queues and Workers
Persist a state machine for each claim and certificate operation, with queued work and limited concurrency. Workers can be replaceable, but the account, order, challenge, certificate and deployment state must survive replacement. Coordinate operations that share a hostname or TXT owner, and make retries reuse the intended operation instead of creating duplicate orders. Rate-limit handling should follow the actual error and provider guidance.
Store certificate/private-key versions as matched pairs with access limited to the required issuers and serving endpoints. Encryption at rest does not compensate for broad read permission. Distribute updates through the edge’s supported mechanism and verify SANs, chain and key match. Test whether the mechanism preserves active connections; a generic reload claim does not guarantee availability for every proxy or configuration.
RSA and ECDSA Certificate Options
Dual RSA/ECDSA serving can be useful for a measured client-compatibility need when the TLS endpoint supports it. It does not guarantee speed improvements or support for every legacy client, and it adds separate key, chain and renewal responsibilities. The Nginx and Apache dual RSA/ECDSA guide covers those prerequisites. Treat dual certificate algorithms separately from IPv4/IPv6 dual-stack networking.
Apex Routing and Provider Features
A standard CNAME cannot coexist with the apex SOA/NS data. ALIAS, ANAME and CNAME flattening are provider-specific features with different support and answer behavior. The apex CNAME and flattening guide compares them. If unavailable, use stable A/AAAA targets supported by the platform or an appropriate subdomain plan. Explain the actual choice in onboarding and publish IPv6 only where the service supports the complete IPv6 path.
Issuance Capacity and Renewal Scheduling
Account for Concentrated Onboarding
A large partner launch can concentrate issuance even when every DNS challenge is valid. Capacity planning needs the actual CA quota scopes, shared registered domains where relevant, account behavior and renewal priorities. Count pending and failed work as well as completed certificates so retries do not amplify a temporary failure into a larger issuance burst.
Prepare verified domains ahead of the deadline and use a bounded queue that respects applicable limits and retry guidance. SAN grouping can couple otherwise independent tenants’ validation and key lifecycles; wildcards have limited name scope. The Let’s Encrypt rate-limit and SAN planning guide discusses these tradeoffs. Pacing reduces peaks but does not make quotas irrelevant or ensure a shared DNS failure can be avoided.
Delegate the Exact Challenge Owner
A customer can delegate the exact challenge owner with a CNAME, for example from _acme-challenge.example.com to a unique target such as claim-123.acme.yourapp.net. that your authorized automation controls. The example identifier is a placeholder; bind the real target to the specific verified claim. Let’s Encrypt follows suitable CNAME or NS delegation, while client update support must be configured separately. Delegating this owner does not also delegate _acme-challenge.api.example.com, which is a different DNS name.
The cert-manager documentation describes its DNS01 solvers and provider integrations. For CNAME-based delegation, cert-manager does not follow the target for updates by default: configure cnameStrategy: Follow with target-zone credentials. Other ACME clients use their own settings. Delegation grants ongoing validation capability while present; explain this to the customer and include removal in offboarding.
Tenant and Credential Boundaries
Scope DNS Access and Domain Claims
Limit DNS credentials to the necessary zones and operations where supported. Record-level TXT-only access is a desired restriction, not a capability to assume every provider offers. Separate credentials or a validation zone can reduce unrelated access. Keep secrets out of repositories and logs, restrict who can retrieve them, and plan rotation so the replacement is verified before the existing renewal path loses access.
Challenge delegation can avoid collecting a customer’s broad DNS credential, but gives the platform continuing validation authority for the delegated names. It does not by itself prove which tenant is entitled to claim them. Maintain fresh tenant-bound verification and one active internal tenant binding per hostname. On removal or transfer, disable old routing and future issuance, require new verification for reassignment, and coordinate removal of obsolete customer DNS/delegation records.
Diagnose CAA Authorization
Inspect the relevant CAA set for every requested identifier and explain the actual blocking condition: issuer, wildcard policy, supported account constraint, method restriction or lookup error. Do not respond to all failures by asking the customer to remove CAA. If the planned primary and backup providers are necessary, ensure both are appropriately authorized. A valid TXT response does not bypass that policy.
Certificate Deployment and Tenant Routing
Update the Edge and Verify Fresh Connections
Distribute a consistent certificate/key version to each required edge and use its supported atomic update or reload path. Check fresh connections for the intended SNI before declaring deployment complete. TLS selects the certificate during the handshake; the HTTP Host or HTTP/2-3 :authority field is processed later. An HTTP routing decision cannot retroactively select the certificate already presented.
After TLS, route the HTTP target only through the verified active hostname-to-tenant map and check that the connection context is appropriate for that origin. Reject unknown or unauthorized names rather than sending them to a default tenant. Raw SNI/Host string equality is not a universal rule for every trusted gateway or connection-sharing setup; enforce the platform’s actual permitted origins and tenant boundaries. Keep issuance independent of serving, while monitoring when the currently served certificate will expire.
When HTTP-01 Fits
HTTP-01 remains suitable when the public domain’s port-80 challenge path can reach the correct response, including customer names routed to a shared platform solver. It is not a method for arbitrary private internal names, and a private-only endpoint is insufficient for public CA validation. RFC 8555 defines the protocol. Choose based on maintainable reachability and authorization rather than a fixed first-party versus customer-domain rule.
Common Onboarding Failures
Authoritative Publication and Resolver Caches
Verify the exact TXT owner at the authoritative DNS service and account for recursive caches. An API response, one internal resolver and every CA vantage point are different observations. Previously cached positive data retains its prior TTL; negative responses have separate SOA-based timing. Lowering TTL now does not purge either. Record the observed state and next retry instead of displaying a universal propagation countdown.
Wildcard Authorization and CAA
If issuewild is absent from the relevant CAA set, issue also governs wildcard issuance. If issuewild is present, it governs wildcards instead. A certificate containing both example.com and *.example.com needs authorization for each identifier. Make readiness checks reflect those rules; the absence of issuewild alone is not a wildcard rejection. An alternate allowed CA still requires configured accounts and validation support.
Distinguish DNSSEC from Delegation Failures
When validating resolvers return SERVFAIL, investigate DNSSEC chain state and other DNS errors rather than assuming a random delay. Compare the current parent DS with the authoritative keys and signatures through the supported DNSSEC troubleshooting process. Glue and delegation determine how servers are reached and can fail independently. Preserve a valid trust chain during changes; merely avoiding an ACME schedule overlap does not establish validity.
Give Correct Apex Instructions
Do not instruct every customer to add an ordinary apex CNAME. Offer only the routing methods supported by that customer’s DNS provider and your edge, including stable A/AAAA addresses where applicable. Keep this distinct from challenge delegation at _acme-challenge.example.com. An apex traffic record can route requests correctly while certificate issuance or platform verification is still incomplete.
Planning a Large Tenant Launch
Readiness Checks Before the Traffic Change
For a planned large launch, inventory customer names and require verified tenant claims before scheduling certificate work. Test the actual DNS providers or delegated zones, CAA policy, DNSSEC state and certificate distribution. Keep the certificate ready at every intended edge before moving application traffic where the architecture permits. This is a planning scenario, not evidence of a particular number of domains processed or a guaranteed completion time.
Use failure states that distinguish missing customer action, DNS publication delay, authorization failure, CA limits and deployment failure. Apply bounded backoff appropriate to the cause and surface the responsible next action. A provider confirming TXT creation before publication requires a publication check; a stale DS requires a DNSSEC correction. Treating both as repeated order retries wastes time and can consume quota.
Implementation Sequence
Persist State Through Activation and Removal
A practical state sequence is claim requested, platform verified, challenge prepared, DNS visible, CA validated, issued, deployed and active. Track failures and removal explicitly. Use DNS adapters that preserve concurrent values, protected versioned key/certificate storage and an edge that acknowledges deployment. Certificate algorithm choice is separate from network dual-stack support. Test the entire sequence, including repeated jobs and interrupted workers, before expanding provider coverage.
The customer interface should show the exact record owner, type, target and purpose, separating platform verification, CA delegation and traffic routing. Avoid promising one-click setup when the provider integration or user authorization is absent. Show concrete pending actions and observed verification results, and provide a support path tied to the operation identifier so troubleshooting can follow the same persisted state.
With cert-manager, verify the documented solver, permissions and delegation behavior rather than assuming it manages the platform’s tenant claims. For direct integrations, start with providers whose operations and recovery paths you can test. Cloudflare’s API-token guide explains selecting permissions and resources; zone-level DNS edit access is not a promise of TXT-only access. Assess each other provider’s credential model independently.
Verify the Complete Domain Lifecycle
A domain is ready when the current tenant claim is authorized, the CA has issued suitable coverage, the correct certificate is deployed, and application traffic reaches only the intended tenant. DNS-01 can prepare the CA proof before traffic moves, but does not combine these checks. Monitor renewal and the live certificate separately, with enough time to correct failures before expiry.
Maintain the full lifecycle after activation: DNS authority and delegation, account state, key access, certificate renewal, distribution and eventual domain removal. Require fresh authorization before reassignment and prevent stale targets from becoming automatic claims for another tenant. On key compromise, coordinate a fresh key, replacement, revocation and verified deployment. Successful onboarding should produce evidence and ownership for these continuing tasks, not an assumption that they will never need attention.
