Skip to main content

Azure DNS

Authenticate to Azure DNS with a service-principal (app registration) scoped to the DNS zone. The backend supports public zones, private zones, and the Azure China / Government sovereign clouds.

Prerequisites​

  • An Azure subscription with the DNS zone provisioned.
  • Permission to create an app registration + client secret in the tenant.
  • Permission to assign RBAC on the zone resource.

Create the service principal​

az ad app create --display-name certautopilot-dns
az ad sp create --id <appId-from-previous-step>
az ad app credential reset --id <appId> --years 2
# → capture appId, tenant (homeTenantId), and the printed password (client_secret)

az role assignment create \
  --assignee <appId> \
  --role "DNS Zone Contributor" \
  --scope /subscriptions/<subId>/resourceGroups/<rg>/providers/Microsoft.Network/dnsZones/<zone>

For private zones use privateDnsZones/<zone> and the Private DNS Zone Contributor role.

Add the credential​

  1. Settings → DNS Credentials → New → Azure DNS.
  2. Fill in:
    • Tenant ID — the AAD tenant GUID.
    • Client ID — the app registration ID.
    • Client secret — the password from the reset command above.
    • Subscription ID — the subscription the zone lives in.
    • Resource group — the RG the zone lives in.
    • Zone name (optional): set when multiple zones share an apex.
    • Private zone: ON when the zone is a Private DNS Zone.
    • Environment: public (default), china, or usgovernment.
  3. Test connectivity → Save.

Config fields​

FieldRequiredPurpose
tenant_idyesAzure AD tenant.
client_idyesApp registration ID.
client_secretyesApp-registration password.
subscription_idyesSubscription GUID.
resource_groupyesResource group containing the zone.
zone_namenoPin to one zone when multiple share an apex.
private_zonenoSet true for Private DNS Zones.
environmentnopublic / china / usgovernment.

Propagation​

Azure DNS typically propagates within 60 seconds globally. For private zones, propagation is effectively instant within the linked VNets.

Rotating the client secret​

Generate a new secret in the app registration, paste it into the credential form, save. The old secret stays valid until you remove it in Azure — overlap them for zero downtime.

Troubleshooting​

"AADSTS7000215: Invalid client secret"​

Client secret is wrong, expired, or rotated. Generate a fresh one in the app registration and paste it in.

"AuthorizationFailed: does not have authorization to perform action"​

RBAC assignment is missing or scoped to the wrong resource. Re-run az role assignment create with the exact zone scope.

Private zone DNS-01 fails​

CAs validate over the public internet. Private zones work for internal clients only. For a public cert, you need a public zone — or switch to a split-horizon setup where the challenge record lives in the public view.

See also​