Announcing the preview of Domain Management API


Hi all,

It is my pleasure to announce the availability of the Domain Management Preview feature in the beta version of Azure AD Graph API. Domain Management allows you to add, verify, update and remove domains associated with your Azure AD tenant. This article shows you how to add a new domain (contoso.com) to an existing Azure AD tenant (contoso.onmicrosoft.com) using the Graph API, and configure it for use with Exchange Online for mail routing.

If you’re not familiar with the Graph API, you may want to review the Quickstart for the Azure AD Graph API article to get an overview of prerequisites and requirements for using the API.

 

Optional: List existing domains in my Azure AD tenant

Here, I issue a request to fetch the list of Domain entities in my Azure AD tenant, which returns a single domain named contoso.onmicrosoft.com:

REQUEST

GET https://graph.windows.net/contoso.onmicrosoft.com/domains?api-version=beta

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com
  /$metadata#domains",

       "value":[

              {

                     "authenticationType":"Managed",

                     "availabilityStatus":null,

                     "isAdminManaged":true,

                     "isDefault":true,

                     "isInitial":true,

                     "isRoot":true,

                     "isVerified":true,

                     "name":"contoso.onmicrosoft.com",

                     "supportedServices":["Email","OfficeCommunicationsOnline"]

              }

       ]

}

 

 

Step 1: Add a new domain (contoso.com) to Azure AD tenant

To add a new Domain entity, issue a POST request with the required properties in the request body. Here is an example of creating a new domain named contoso.com:

REQUEST

POST https://graph.windows.net/contoso.onmicrosoft.com/domains?api-version=beta

BODY

{

       "name" : "contoso.com"

}

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#domains/@Element",

       "authenticationType":"Managed",

       "availabilityStatus":null,

       "isAdminManaged":false,

       "isDefault":false,

       "isInitial":false,

       "isRoot":false,

       "isVerified":false,

       "name":"contoso.com",

       "supportedServices":[]

}

 

Once the Domain entity is created for contoso.com, its properties are returned with the isVerified property set to “false”, indicating that it is an unverified domain.

 

 

Step 2: Request the verification DNS records required to verify the domain

You can’t use the domain with your Azure AD tenant until you have successfully verified that you own this domain. To verify the ownership of the domain, first, use the verificationDnsRecord navigation property to retrieve the DNS verification records:

REQUEST

GET https://graph.windows.net/contoso.onmicrosoft.com/domains/contoso.com/verificationDnsRecords?api-version=beta

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#domainDnsRecords",

       "value":[

              {

                     "odata.type":"Microsoft.DirectoryServices.DomainDnsTxtRecord",

                     "dnsRecordId":"aceff52c-06a5-447f-ac5f-256ad243cc5c",

                     "isOptional":false,

                     "label":"contoso.com",

                     "recordType":"Txt",

                     "supportedService":null,

                     "ttl":3600,

                     "text":"MS=ms86120656"

              },

 

              {

                     "odata.type":"Microsoft.DirectoryServices.DomainDnsMxRecord",

                     "dnsRecordId":"5fbde38c-0865-497f-82b1-126f596bcee9",

                     "isOptional":false,

                     "label":"contoso.com",

                     "recordType":"Mx",

                     "supportedService":null,

                     "ttl":3600,

                     "mailExchange":"ms86120656.msv1.invalid",

                     "preference":32767

              }

       ]

}

 

To prove that you own the domain, you need to sign in to your account at your DNS host to create either a TXT or MX record based on the verification DNS records returned.

 

 

Step 3: Invoke verify function to verify domain ownership

Once you have created the necessary DNS record at your DNS host, invoke the Verify function to start the verification process:

REQUEST

POST  https://graph.windows.net/contoso.onmicrosoft.com/domains/contoso.com/verify?api-version=beta

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#domains/@Element",

       "authenticationType":"Managed",

       "availabilityStatus":"AvailableImmediately",

       "isAdminManaged":true,

       "isDefault":false,

       "isInitial":false,

       "isRoot":true,

       "isVerified":true,

       "name":"contoso.com",

       "supportedServices":[]

}

 

Upon successful verification, the contoso.com Domain properties are returned, with isVerified set to “true”.

 

 

Step 4: Indicate which services will be using this domain (e.g., Email)

Indicate what you will be using this domain for by configuring the supportedServices attribute on the domain entity. To do so, you must first retrieve the Domain entity for the contoso.com domain:

REQUEST

GET https://graph.windows.net/contoso.onmicrosoft.com/domains/contoso.com?api-version=beta

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#domains/@Element",

       "authenticationType":"Managed",

       "availabilityStatus":null,

       "isAdminManaged":false,

       "isDefault":false,

       "isInitial":false,

       "isRoot":false,

       "isVerified":true,

       "name":"contoso.com",

       "supportedServices":[]

}

 

In this case, the domain has not yet been configured for any use. To enable the domain for use with Exchange Online for mail routing, add “Email” to the supportedServices attribute array and issue a PATCH request on the attribute:

REQUEST

PATCH  https://graph.windows.net/contoso.onmicrosoft.com/domains/contoso.com?api-version=beta

BODY

{

       "supportedServices":["Email"]

}

 

Verified domains can be configured for various uses. For example, a tenant admin can configure a verified domain for Yammer service activation and multiple domains for O365 domain full redelegation in O365 admin portal. These configurations will be reflected in the supportedServices attribute on the Domain entity. These values are read-only. You cannot use Graph API to add/remove them. Values which you can add/remove using Graph API includes:

  1. Email – For Exchange Online mail routing
  2. OfficeCommunicationsOnline – For use with Skype for Business
  3. Intune – For use with Intune Online Service.

I will not cover the list of read-only values in this article, but they will be made available shortly through MSDN documentation.

 

 

Step 5: Request for DNS configuration based on domain usage configured

Now that you have updated the supportedServices attribute on the Domain entity, you can request for a list of DNS records which you need to configure at your DNS host by using the serviceConfigurationRecords navigation property:

REQUEST

GET  https://graph.windows.net/contoso.onmicrosoft.com/domains/contoso.com/serviceConfigurationRecords?api-version=beta

 

RESPONSE

{

       "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#domainDnsRecords",

       "value":[

              {

                     "odata.type":"Microsoft.DirectoryServices.DomainDnsMxRecord",

                     "dnsRecordId":"2b672ab0-0bee-476f-b334-be436f2449bd",

                     "isOptional":false,

                     "label":"contoso.com",

                     "recordType":"Mx",

                     "supportedService":"Email",

                     "ttl":3600,

                     "mailExchange":"contoso-com.mail.protection.outlook.com",

                     "preference":0

              },

              {

                     "odata.type":"Microsoft.DirectoryServices.DomainDnsTxtRecord",

                     "dnsRecordId":"62bea837-a0d7-4466-b6d9-ff6bd1db8671",

                     "isOptional":false,

                     "label":"contoso.com",

                     "recordType":"Txt",

                     "supportedServices":"Email",

                     "ttl":3600,

                     "text":"v=spf1 include: spf.protection.outlook.com ~all"

              },

              {

                     "odata.type":"Microsoft.DirectoryServices.DomainDnsCnameRecord",

                     "dnsRecordId":"eea5ce9e-8deb-4ab7-a114-13ed6215774f",

                     "isOptional":false,

                     "label":"autodiscover.contoso.com",

                     "recordType":"CName",

                     "supportedServices":"Email",

                     "ttl":3600,

                     "canonicalName":"autodiscover.outlook.com"

              }

       ]

}

 

 

Features that are not supported

You cannot use Graph API to enable a verified domain for federation, nor configure federation settings for an existing federated domain. You have to do so via Azure AD PowerShell. However, any domain changes made via Azure AD PowerShell will be reflected in Graph API.

 

 

Feedback

We'd love to hear from you.  Please give us feedback through our forums or through comments below.

  

Comments (7)

  1. DongHyung Kim says:

    Hi, AAD Graph team

    It is great article!!

    Unfortunately, I got a problem that i try to post request such as add a new domain. It was return 403 error when i request post type

    Is post method differ from get method in AzureAD authorization token?

    if you possible, informed of post method essential request header.

    Thanks in advance.

  2. Carl Inglis says:

    When adding a domain to a customer (for who we're a CSP), what authentication token(s) should we use?

    Is there a worked example available for CSPs who want to add domains to their customer's tenants?

    Thanks!

  3. Miguel says:

    Hi there,

    We are trying to manage CSP customer's domains using the beta version of the Domain Management API, when i try to list all domains works' all good but when trying to add a new domain we always get the "Insufficient privileges to complete the operation" error.

    Is there any way to adjust these permissions?

    Thanks for your time.

    Best regards,

    Miguel Moreno

  4. Chun Yong Chua says:

    All, currently, Domain Management requires the use of Implicit or Authorization Code flow only. Further, the login user must have Tenant Admin rights in order to add/verify new domains. Therefore, the only possible Graph permission scope that can be used with Domain Management is Directory.AccessAsUser.All.

    I presume most of you are running into problem is because you are using client credential flow. Right now, you can't use client credential flow since none of the existing app permission scopes have sufficient rights to let you perform domain management. We are in the process of adding a new app permission scope just for domain management. This should happen within the next couple of weeks.

    Thanks.

  5. Carl Inglis says:

    "Values which you can add/remove using Graph API includes"

    Is there a list of which supportedServices are required for which servicePlans?

    Thanks,

    Carl

  6. Anton says:

    Are there any updates on this? When will this feature be out of beta and into any official API version?

  7. Sinclair says:

    How do we pass the IDN domains to this API?

Skip to main content