Microsoft Graph or the Azure AD Graph

Microsoft Graph team

February 20th, 2019 1

UPDATE March 1, 2022:

Please note that we have postponed the retirement date for Azure AD Graph. The Azure AD Graph retirement date will be postponed through at least the end of 2022. For the most up to date information about end of support for Azure AD Graph, please read the blog post: Azure AD: Change Management Simplified – Microsoft Tech Community.

—————————————-

Howdy folks,

We’ve seen a few posts recently on Stack Overflow from developers asking whether they should be using Microsoft Graph (developer.microsoft.com/graph) vs Azure AD Graph (graph.windows.net). So we thought we’d provide some guidance, as well as a bit of a roadmap to clarify things, for new and existing developers who require directory-based features. In general, we recommend the use of Microsoft Graph over Azure AD Graph, as Microsoft Graph is where we are investing for Microsoft cloud services.

Roadmap for AAD Graph and Microsoft Graph

First of all, we’ll lay out the roadmap for Microsoft Graph (as it is related to Azure AD Graph functionality). In each of the sections below we’ll also highlight the opportunities and implications for developers.

Two endpoints, different functionality

Currently (as of February 2019) Microsoft Graph supports most of the directory features that Azure AD Graph supports, but not all. In some cases, Microsoft Graph supports functionality that is not in Azure AD Graph (such as ability to make $select projection queries).

Even with those gaps, we strongly recommend that developers start using Microsoft Graph over Azure AD Graph, unless those specific gaps prevent you from using Microsoft Graph right now. For a list of the high level gaps, as of February 2019, please see the end of this blog post for more details.

Microsoft Graph closing the gap with Azure AD Graph

The Microsoft Graph team is working hard to close the gap between Microsoft Graph and Azure AD Graph functionality, making it easier for developers to choose Microsoft Graph. We will also start to introduce newer directory features on Microsoft Graph (and in some cases only on Microsoft Graph). You’ll start to see the gap closure and new features over the coming months. Please monitor both http://developer.microsoft.com/graph/blogs and the Microsoft Graph changelog to see this happen real-time so to speak!

Microsoft Graph supports all functionality exposed by Azure AD Graph

At some point in the near future (we hope within 6 months) Microsoft Graph will support all functionality that Azure AD Graph offers (and more). At this point developers building new apps (or integrating an existing app with Microsoft cloud services) will be directed to use Microsoft Graph in favor of Azure AD Graph.

Update 2/20/2019: Starting February 23^rd 2019, we will prevent newly registered apps from calling three older Azure AD Graph versions 0.5, 0.8 and 0.9. All scenarios in these versions are fully supported in Microsoft Graph. For existing apps calling the AAD Graph 0.5-0.9 versions you have until July 1, 2019 to migrate your app to Microsoft Graph API as these versions will be deprecated.

NOTE: As we start removing support for non-GA versions of Azure AD Graph (versions 0.5-0.9) we will deprecate additional GA versions in the future. We urge developers to migrate to Microsoft Graph. Regardless, the Azure AD Graph GA endpoint will remain fully available for all applications including production applications. We will continue to closely monitor this API, fix service issues and strive to continue to provide 99.99% service availability.

For developers with existing apps that call Azure AD Graph, we will provide guidance for those who want to switch their apps over to Microsoft Graph (from Azure AD Graph). Additionally, we’ll do it in such a way that existing users for your applications won’t need to re-consent to your application to access directory data through Microsoft Graph.

Client libraries

While we continue to support the Azure AD Graph client library, this is only available for .Net applications and it is maintenance mode. On the other hand, Microsoft Graph client libraries are available on multiple platforms and languages, that enables you to have more choice in how you can use directory data in apps for your customers.

We’d like to hear from you

We hope this post clarifies the future of both Microsoft Graph and Azure AD Graph, and how you should think about developing against these APIs. In general, we recommend the use of Microsoft Graph over Azure AD Graph, as Microsoft Graph is where we are investing for Microsoft cloud services. As always, we’d like to hear what you think of our roadmap plan.

Gaps between Microsoft Graph and Azure AD Graph

AAD Graph Capability	Status in Microsoft Graph (February 20, 2019)
1. Differential query (aka delta sync) for users, groups and organizational contacts	GA availability with Delta Query. Delta query on organizational contacts is not available but is planned (see below). Sync from now and some other new capabilities like scoping filters (track changes on one or more users or groups) are supported in Delta Query.
2. Organizational contact resource type	Preview recently updated with a restructured resource, as we ready for release to GA, very soon.
3. Management of applications including: a. Application and service principal entity types b. Managing assignment of applications to users and groups c. Assigning OAuth permissions to apps	Application and service principal are available in preview. Extensive breaking changes are planned over the coming few months for application APIs, in preview, before this rolls out to Microsoft Graph v1.0.
4. Partner admin on behalf of capability (for resellers and syndicators who are part of the Cloud Solution Provider program)	GA availability. See CSP support in Microsoft Graph.
5. Domain resource type (mainly relevant for Cloud Solution Providers)	GA availability. See Domain. This now includes the ability to forcefully delete a domain.
6. Contracts resource type (only relevant for Cloud Solution Providers)	GA availability. See Contract.
7. Registering directory schema extension definitions	GA availability. Extending resources with application data is available with Extensions and schema extensions. NOTE: Not available for extending application or service principal resource types.
8. Batching	Available in preview. See JSON batching
9. Missing properties on the User resources (sipProxyAddress, otherMails, licenseDetails)	GA availability: See User. This was recently updated to add otherMails, faxNumber, employeeId and other properties. With the exception of managing users in a B2C tenant (see below), the User resource in Microsoft Graph is now at parity with Azure AD Graph, and contains additional properties and capabilities (like restoring deleted users) over and above Azure AD Graph.
10. GetObjectsByObjectIds method	GA availability. See getByIds method.
11. IsMemberOf method	Not planned. Use checkMemberGroups method instead.
12. Manage users in a B2C tenant (set local accounts, sign in names)	Coming soon to preview, in a few months.