Automating DNS-01 with DNS APIs

The Promise and the Problem

DNS-01 validation unlocks capabilities HTTP-01 can't touch: wildcard certificates, internal servers, and multi-server deployments. But it comes with a catch—your ACME client needs API access to your DNS provider.

This guide covers the practical implementation of DNS-01 automation, from basic API integration to security-hardened architectures using CNAME delegation.

How DNS-01 Validation Works

When you request a certificate using DNS-01:

DNS Provider API Integration

# Install Cloudflare plugin
sudo snap install certbot-dns-cloudflare

# Install Route53 plugin  
sudo snap install certbot-dns-route53

# Install Azure DNS plugin
pip install certbot-dns-azure

# Cloudflare example
export CF_Token="your-api-token"
export CF_Account_ID="your-account-id"
acme.sh --issue -d example.com -d *.example.com --dns dns_cf

# Route53 example
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
acme.sh --issue -d example.com --dns dns_aws

# Azure DNS example
export AZUREDNS_SUBSCRIPTIONID="your-sub-id"
export AZUREDNS_TENANTID="your-tenant-id"
export AZUREDNS_APPID="your-app-id"
export AZUREDNS_CLIENTSECRET="your-secret"
acme.sh --issue -d example.com --dns dns_azure

certbot certonly \
  --manual \
  --preferred-challenges dns \
  --manual-auth-hook /path/to/auth-hook.sh \
  --manual-cleanup-hook /path/to/cleanup-hook.sh \
  -d example.com

The Security Problem with DNS APIs

Least-Privilege Approaches

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:GetChange",
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": [
        "arn:aws:route53:::hostedzone/YOUR_ZONE_ID",
        "arn:aws:route53:::change/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "route53:ListHostedZones",
      "Resource": "*"
    }
  ]
}

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Validation     │────▶│  Certificate     │────▶│  Production     │
│  Server         │     │  Storage         │     │  Servers        │
│  (DNS API creds)│     │  (S3, Vault)     │     │  (No DNS creds) │
└─────────────────┘     └──────────────────┘     └─────────────────┘

CNAME Delegation: The Security Sweet Spot

CNAME delegation lets you prove domain control without giving your ACME client access to your primary DNS zone.

How It Works

Instead of creating TXT records directly, you create a permanent CNAME that points _acme-challenge.yourdomain.com to a zone you control separately (or to a service like acme-dns).

_acme-challenge.example.com  CNAME  abc123.auth.acme-dns.io

# Using acme-dns with certbot
certbot certonly \
  --manual \
  --manual-auth-hook /etc/letsencrypt/acme-dns-auth.py \
  --preferred-challenges dns \
  -d example.com -d *.example.com

# Primary zone (example.com)
_acme-challenge.example.com     CNAME  _acme-challenge.acme.example.com
_acme-challenge.www.example.com CNAME  _acme-challenge.www.acme.example.com

# Delegated zone (acme.example.com) - separate credentials
_acme-challenge.acme.example.com      TXT  [validation token]
_acme-challenge.www.acme.example.com  TXT  [validation token]

Handling DNS Propagation

DNS changes don't happen instantly. After creating a TXT record, it may take seconds to minutes before all DNS servers see it.

The timings below are typical observed ranges, not provider SLAs; real-world propagation can be faster or slower depending on resolver caches and your TTLs.

Propagation Timing

Client Configuration

certbot certonly \
  --dns-cloudflare \
  --dns-cloudflare-propagation-seconds 60 \
  -d example.com

# Default wait is 120 seconds
# Use --dnssleep to override
acme.sh --issue -d example.com --dns dns_cf --dnssleep 300

# Manual check
dig TXT _acme-challenge.example.com @8.8.8.8

Wildcard + Apex Certificate Gotcha

_acme-challenge.example.com  TXT  "token-for-apex"
_acme-challenge.example.com  TXT  "token-for-wildcard"

Most DNS providers support multiple values, but some don't. If yours doesn't:

• Issue separate certificates for apex and wildcard
• Use a provider that supports multi-value TXT records
• Use CNAME delegation to a provider that does

Provider-Specific Configurations

# Certbot
dns_cloudflare_api_token = your-scoped-token

# acme.sh
export CF_Token="your-scoped-token"
export CF_Zone_ID="your-zone-id"  # Optional but recommended

# Certbot
certbot certonly \
  --dns-route53 \
  --dns-route53-propagation-seconds 30 \
  -d example.com

# acme.sh
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
acme.sh --issue -d example.com --dns dns_aws

# Create service principal
az ad sp create-for-rbac --name "acme-dns-automation"

# Assign DNS Zone Contributor role (scoped to zone)
az role assignment create \
  --assignee <app-id> \
  --role "DNS Zone Contributor" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Network/dnszones/<zone>

# Create service account
gcloud iam service-accounts create acme-dns \
  --display-name "ACME DNS Automation"

# Grant dns.admin role (or more restrictive custom role)
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:acme-dns@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/dns.admin"

Renewal Automation

DNS-01 certificates renew the same way they're issued. Ensure:

• Credentials remain valid — API tokens don't expire unexpectedly
• CNAME records persist — If using delegation, don't accidentally delete them
• Renewal runs regularly — Certbot's systemd timer runs twice daily by default

In multi-environment setups, run DNS-01 renewals from a controlled validation automation host that can reach both your ACME endpoint and your DNS API or delegated service, then distribute certificates to other environments.

# Test renewal
certbot renew --dry-run

# Check timer status
systemctl status certbot.timer

Decision Matrix: Which Approach?

Common Failures and Fixes

Security Checklist

Related Resources

Pair this guide with "Which DCV Method to Automate?" to decide when DNS-01 should be your default and when HTTP-01 or TLS-ALPN-01 will be simpler and easier to operate.