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.
Comments
Anonymous
October 25, 2015
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.Anonymous
October 29, 2015
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!Anonymous
November 12, 2015
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 MorenoAnonymous
November 14, 2015
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.Anonymous
January 20, 2016
"Values which you can add/remove using Graph API includes" Is there a list of which supportedServices are required for which servicePlans? Thanks, CarlAnonymous
January 26, 2016
Are there any updates on this? When will this feature be out of beta and into any official API version?Anonymous
January 26, 2016
How do we pass the IDN domains to this API?