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 |
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:
- Email – For Exchange Online mail routing
- OfficeCommunicationsOnline – For use with Skype for Business
- 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 |
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.