How to use Azure DNS

martgras edited this page Mar 26, 2018 · 3 revisions


You need the Azure Cli 2.0 tools to create a service principal for access to your DNS Zone. Either install Azure Cli 2.0 locally or use the Azure Cloud Shell


Log-in to Azure

(not required when using the Azure Cloud Shell)

az login 
    "cloudName": "AzureCloud",
    "id": "12345678-9abc-def0-1234-567890abcdef",
    "isDefault": true,
    "name": "myAzureSubscription",
    "state": "Enabled",
    "tenantId": "11111111-2222-3333-4444-555555555555",
    "user": {
      "name": "",
      "type": "user"

List your DNS Zones

az network dns zone list
    "etag": "00000002-0000-0000-f641-73c64955d301",
    "id": "/subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/exampledns_rg/providers/Microsoft.Network/dnszones/",
    "location": "global",
    "maxNumberOfRecordSets": 5000,
    "name": "",
    "nameServers": [
    "numberOfRecordSets": 11,
    "resourceGroup": "exampledns_rg",
    "tags": {},
    "type": "Microsoft.Network/dnszones"

Create a service principal

The service principal is used to grant access to the DNS Zone using the id value from the previous commands output

(See for more details )

az ad sp create-for-rbac --name  "AcmeDnsValidator" --role "DNS Zone Contributor" --scopes /subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/exampledns_rg/providers/Microsoft.Network/dnszones/
  "appId": "3b5033b5-7a66-43a5-b3b9-a36b9e7c25ed",
  "displayName": "AcmeDnsValidator",
  "name": "http://AcmeDnsValidator",
  "password": "1b0224ef-34d4-5af9-110f-77f527d561bd",
  "tenant": "11111111-2222-3333-4444-555555555555"
Note: Dealing with multiple DNS Zones

Because by default saves the credentials in ~/ you have to use the same credentials for all your DNS Zones*.

For example if you are also managing certificates for you can grant the the service principal acccess to the DNS Zone with:

az ad sp create-for-rbac --name  "AcmeDnsValidator" --role "DNS Zone Contributor" --scopes /subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/exampledns_rg/providers/Microsoft.Network/dnszones/ /subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/deleteme_rg/providers/Microsoft.Network/dnszones/

or grant access to the service principal after you created it

az role assignment create --assignee 3b5033b5-7a66-43a5-b3b9-a36b9e7c25ed --role "DNS Zone Contributor" --scope /subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/deleteme_rg/providers/Microsoft.Network/dnszones/

*If you want to use different credentials instead use the --accountconf switch to specifiy a configuration file

Limit access permissions to TXT records

In Azure DNS you can limit the permissions for the service principal further and only grant permissions to modifiy TXT records for a given DNS Zone. (See for more details)


  • Azure Subscription is 12345678-9abc-def0-1234-567890abcdef
  • The resource group of your DNS Zone is exampledns_rg
  • The DNS Zone is
#!/usr/bin/env sh
# Create a custom RBAC role that grants permissions to modifiy only TXT records
    "Name": "DNS TXT Contributor", 
    "Id": "",
     "IsCustom": true, 
    "Description": "Can manage DNS TXT records only.", 
    "Actions": [ 
    "NotActions": [ 
    "AssignableScopes": [ 
az role definition create --role-definition "$dnscustomrole"
# Create a new service principal and grant permissions to modify TXT recornds in the give DNS Zone
az ad sp create-for-rbac --name  "AcmeDnsValidator" --role "DNS TXT Contributor" --scopes "/subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/exampledns_rg/providers/Microsoft.Network/dnszones/ 

# or  grant an existing service principal permissions to modify TXT recornds in the give DNS Zone
#az role assignment create  --assignee 3b5033b5-7a66-43a5-b3b9-a36b9e7c25ed --scope "/subscriptions/12345678-9abc-def0-1234-567890abcdef/resourceGroups/exampledns_rg/providers/Microsoft.Network/dnszones/" --role "DNS TXT Contributor"

You can now use

export AZUREDNS_SUBSCRIPTIONID="12345678-9abc-def0-1234-567890abcdef"
export AZUREDNS_TENANTID="11111111-2222-3333-4444-555555555555"
export AZUREDNS_APPID="3b5033b5-7a66-43a5-b3b9-a36b9e7c25ed"          # appid of the service principal
export AZUREDNS_CLIENTSECRET="1b0224ef-34d4-5af9-110f-77f527d561bd"   # password from creating the service principal --issue --dns dns_azure -d -d
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.