Azure Private DNS
Azure Private 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 private DNS zones.
On this page
Azure Private DNS service principal permissions
- Credential type
- Microsoft Entra client secret
- Preview access
- Reader
- Apply access
- Private DNS Zone Contributor
- API endpoint
- DNSMigrator uses the provider's fixed API endpoint.
Additional access
DNSControl id
{
"TYPE": "AZURE_PRIVATE_DNS"
}Create credentials
Register a single-tenant Microsoft Entra app, create its client secret, and assign it access to the resource group containing your private DNS zones.
Access you'll grant
Reader
Private DNS Zone Contributor
Before you start
- An Azure subscription with the Azure Private 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
DNSMigrator Private DNSunder Name, choose the single-tenant option for your directory under Supported account types, leave Redirect URI (optional) empty, and select Register.App nameDNSMigrator Private DNSScreenshot: 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 private DNS zones, then choose Access control (IAM) → Add → Add role assignment. On Job function roles, search for Reader for preview-only access or Private DNS Zone Contributor for apply, select the role, and choose Next.
Preview roleReaderApply rolePrivate DNS 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 Private DNS, 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 Private DNS Zone Contributor to the app at the resource group named in the form. DNS Zone Contributor is for public Azure DNS and doesn't grant privateDnsZones access.
The private-zone list is empty
Check the Subscription ID and resource-group spelling. DNSMigrator only lists private DNS zones in that one group; a role on another 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
- Private 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 private DNS zones. |
| Resource groupresourceGroup | Required | Azure portal → Resource groups → the group containing the private DNS zones. Copy its Name exactly. |
Capabilities
- Create zones
- Yes
- List zones
- Yes
- DNSSEC
- Not available through this connection
- Minimum TTL
- Automatic
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
- TXT
- SRV
- PTR
Caveats
- Private zones only resolve inside Azure virtual networks linked to the zone, so changes can't be checked with public DNS lookups.
- Link the zone to your virtual networks after migrating; records auto-registered by VMs are skipped.
- Only A, AAAA, CNAME, MX, PTR, SRV and TXT records are supported; NS and CAA aren't.
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 Private DNS Zone Contributor to the app at the resource group named in the form. DNS Zone Contributor is for public Azure DNS and doesn't grant privateDnsZones access.
- The private-zone list is empty
- Check the Subscription ID and resource-group spelling. DNSMigrator only lists private DNS zones in that one group; a role on another group or on only one zone isn't enough for the group-level list call.