Azure DNS
Azure DNS service principal setup: register a single-tenant Microsoft Entra app, create its client secret, and assign it access to the resource group containing your public DNS zones.
On this page
Azure DNS service principal permissions
- Credential type
- Microsoft Entra client secret
- Preview access
- Reader
- Apply access
- DNS Zone Contributor
- API endpoint
- DNSMigrator uses the provider's fixed API endpoint.
Additional access
DNSControl id
{
"TYPE": "AZURE_DNS"
}Create credentials
Register a single-tenant Microsoft Entra app, create its client secret, and assign it access to the resource group containing your public DNS zones.
Access you'll grant
Reader
DNS Zone Contributor
Before you start
- An Azure subscription with the public Azure DNS zones in one resource group.
- A Microsoft Entra account allowed to register apps; Microsoft's current app-registration guide requires at least Application Developer.
- Microsoft.Authorization/roleAssignments/write at the resource group, such as Role Based Access Control Administrator or User Access Administrator.
- DNSMigrator currently requires a client secret. Microsoft limits client-secret lifetime to 24 months and recommends less than 12 months; plan to replace it before it expires.
Setup steps
0 of 6 done
Register a Microsoft Entra app
In the Microsoft Entra admin center, go to Entra ID → App registrations → New registration. Enter
DNSMigratorunder Name, choose the single-tenant option for your directory under Supported account types, leave Redirect URI (optional) empty, and select Register.App nameDNSMigratorScreenshot: Microsoft Learn, MIT
Copy the application IDs
On the new app's Overview page, copy Application (client) ID and Directory (tenant) ID. These are the Client ID and Tenant ID in the connection form.
Create a client secret
Open Certificates & secrets → Client secrets → New client secret. Enter a description, choose an Expires value that fits your rotation policy, and select Add. Copy the secret's Value immediately; don't copy Secret ID. The value isn't displayed again after you leave the page.
Screenshot: Microsoft Learn, MIT
Choose the Azure role
In the Azure portal, open Resource groups, select the group containing your DNS zones, then choose Access control (IAM) → Add → Add role assignment. On Job function roles, search for Reader for preview-only access or DNS Zone Contributor for apply, select the role, and choose Next.
Preview roleReaderApply roleDNS Zone ContributorScreenshot: Microsoft Learn, CC BY 4.0
Assign the role to the app
On Members, choose User, group, or service principal → Select members, search for
DNSMigrator, select the app, and choose Select. Continue to Review + assign, then select Review + assign again to create the assignment.Enter the connection values
Paste the tenant ID, client ID, client-secret Value, subscription ID, and the exact resource-group name here. The subscription and resource group must be the scope where you assigned the role.
Troubleshooting
AADSTS700016 says the application wasn't found
Tenant ID and Client ID belong to different tenants or one was copied incorrectly. Copy both again from the same app registration's Overview page.
AADSTS7000215 reports an invalid client secret
Paste the client secret Value, not Secret ID. If the value is no longer available or its Expires date passed, create a new client secret and replace the connection.
Azure returns AuthorizationFailed or HTTP 403
Assign Reader or DNS Zone Contributor to the app at the resource group named in the form. Check that the assignment is active and allow time for Azure RBAC changes to propagate.
The zone list is empty
Check the Subscription ID and resource-group spelling. DNSMigrator only lists public DNS zones in that one group; a role on a different group or on only one zone isn't enough for the group-level list call.
Official documentation
- Register an application in Microsoft Entra ID
- Add and manage Microsoft Entra app credentials
- Assign Azure roles using the portal
- DNS Zone Contributor permissions
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| Tenant IDtenantId | Required | App registration → Overview → Directory (tenant) ID. |
| Client (application) IDclientId | Required | App registration → Overview → Application (client) ID. |
| Client secretclientSecret | Required | App registration → Certificates & secrets → Client secrets → Value. Copy it when created; Secret ID is not the credential. |
| Subscription IDsubscriptionId | Required | Azure portal → Resource groups → your group → Overview → Subscription ID. Use the subscription containing the DNS zones. |
| Resource groupresourceGroup | Required | Azure portal → Resource groups → the group containing the public DNS zones. Copy its Name exactly. |
Capabilities
- Create zones
- Yes
- List zones
- Yes
- DNSSEC
- Managed through the API
- Minimum TTL
- Automatic
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
- TXT
- NS
- SRV
- CAA
- PTR
Caveats
- Azure alias records point at Azure resource IDs, which don't exist outside Azure.
- Apex CNAMEs are not allowed. Use an alias record to an Azure resource or A/AAAA records.
Troubleshooting
- AADSTS700016 says the application wasn't found
- Tenant ID and Client ID belong to different tenants or one was copied incorrectly. Copy both again from the same app registration's Overview page.
- AADSTS7000215 reports an invalid client secret
- Paste the client secret Value, not Secret ID. If the value is no longer available or its Expires date passed, create a new client secret and replace the connection.
- Azure returns AuthorizationFailed or HTTP 403
- Assign Reader or DNS Zone Contributor to the app at the resource group named in the form. Check that the assignment is active and allow time for Azure RBAC changes to propagate.
- The zone list is empty
- Check the Subscription ID and resource-group spelling. DNSMigrator only lists public DNS zones in that one group; a role on a different group or on only one zone isn't enough for the group-level list call.