We've seen a few posts recently on Stack Overflow from developers asking whether they should be using Microsoft Graph (graph.microsoft.com) 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 10 May, 2017) 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, open extensions, Office 365 groups and much more).

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 7 April, 2017, 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://dev.office.com/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 to access directory data (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. For newly registered apps we may prevent the app from calling Azure AD Graph.

NOTE: For existing applications that already use Azure AD Graph, nothing changes and it's business as usual. 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.

]]>https://blogs.msdn.microsoft.com/aadgraphteam/2016/07/08/microsoft-graph-or-azure-ad-graph/feed/0Azure AD will now record consent for mobile client appshttps://blogs.msdn.microsoft.com/aadgraphteam/2016/03/04/azure-ad-will-now-record-consent-for-mobile-client-apps/
https://blogs.msdn.microsoft.com/aadgraphteam/2016/03/04/azure-ad-will-now-record-consent-for-mobile-client-apps/#respondFri, 04 Mar 2016 23:26:38 +0000https://blogs.msdn.microsoft.com/aadgraphteam/?p=481We'll be rolling out an update to the way that we record consent grants in the coming weeks. With this change, we will start to centrally record consent given by users to mobile or native client apps (like applications on mobile devices like laptops, PCs, iOS and Android) that access Microsoft APIs (like Microsoft Graph, Office 365 and Azure AD). Recording consent centrally is something that already happens for web apps. Now we are extending this to mobile client apps so that end users and administrators can have a consistent experience for using and managing both types of app.

What does this mean for end users?

Consent is required one-time only per app, and is good across all devices for the same app, which was not the case previously.

App revocation is now possible. Revocation is performed once, and revokes the app across all devices. End user revocation (of the mobile app's access to user data) can be accomplished through the Office 365 portal: https://portal.office.com/account/#apps.

For existing mobile apps that users have already consented (prior to this change), the app continues to work as before. The app will only show up in the Office 365 portal after the user has been asked to re-consent.

What does this mean for administrators?

Admins can now consent for mobile client apps on behalf of their organization.

Admins can apply policy for the app (conditional access and assigning the app to users to control access)

Any operations on mobile client apps (consent, revocation, app assignment, conditional access, sign in etc) will now show up in audit logs.

What does this mean for developers?

Developers will now be able to write apps that can query Azure AD (through Azure AD or Microsoft Graph) to get consented mobile app and any consent or assignment links for those applications.

]]>https://blogs.msdn.microsoft.com/aadgraphteam/2016/03/04/azure-ad-will-now-record-consent-for-mobile-client-apps/feed/0New graph API consent permissionshttps://blogs.msdn.microsoft.com/aadgraphteam/2015/10/06/new-graph-api-consent-permissions/
https://blogs.msdn.microsoft.com/aadgraphteam/2015/10/06/new-graph-api-consent-permissions/#commentsTue, 06 Oct 2015 16:37:00 +0000https://blogs.msdn.microsoft.com/aadgraphteam/2015/10/06/new-graph-api-consent-permissions/Today we're glad to announce a few updates to our Azure AD Graph API permission scopes. Some of these new permission scopes can be consented by non-admin users, enabling greater reach for your applications. This is something the team is really excited about.

The new permission scopes

In addition to the four existing permission scopes (the four listed at the bottom in the Azure Management Portal screenshot below), we've now added four new delegated scopes (and an additional app-only permission scope which is not shown).

In order to enable a number of key scenarios, developers previously needed to request privileged permissions that required an administrator to consent. By introducing a new set of more granular permissions, we've allowed some key scenarios to be enabled for your app that can either be consented by a non-admin user. For example with the "Read all users' basic profiles" you can now build a people picking experience to control access to resources in your application, that non-admin users can consent to. While introducing this additional flexibility for you, we still ensure that privileged operations can only be consented by an administrator. This allows you to create applications that can reach a larger audience, while protecting privileged operations. Additional permissions around groups still require admin consent, but are now less privileged in nature than the pre-existing permission scopes.

Scenario

Permission scopes required

Admin consent required?

People picker - core to many applications is the ability to pick users to control access to resources in your application.

Read all users' basic profiles

No

Org chart navigator - see a user's reports and their management chain.

Read all users' full profiles

Yes

Groups and memberships viewer

Read all users' basic profiles

Read all groups

Yes

Group management service that allows users to create, manage and delete groups. (NOTE the user of the app would need to be in a role that allows for group creation and management).

Read all users' basic profiles

Read and write all groups

Yes

So you might ask - how can we allow an end user to consent to release information to an application about other users in their organization? The new permission "Read all users' basic profiles" (which has the scope claim value "user.readbasic.all") releases only limited information about other users. When querying the user entity, it exposes only enough information to make a people picker useful, without releasing information like phone numbers or location. To be specific, it allows the calling application to get the first name, last name, display name, photo and email address of other users in the organization of the signed-in user.

We've also updated a few of the existing permission scopes:

We've restricted the "Read and write directory data" permission so that it no longer allows the application to reset other user passwords.

We've extended the "Sign in and read user profile" permission to also allow the application to read some basic information about the company (company display name and verified domains) through the tenantDetails entity. NOTE: For any users who have already consented to this permission (prior to this update), the application will not have access to the tenantDetails entity.

Great new permissions topic

Concepts such as delegated vs app-only permissions, and full vs basic profiles for users and groups.

Permission scope details highlighting what each scope is capable of, if it's app-only or delegated, and whether it requires an admin to consent.

What's next?

This change not only introduced new permission scopes, but also an update to our underlying platform that will allow our team to introduce additional permission scopes more quickly. New scopes will be driven by developer and application scenarios and by our principles to align permission scopes along the entities in our API and to explicitly split out new permission scopes for privileged operations (such as changing or resetting passwords).

What do you think?

As always, we'd love to hear more from you all. Are these new permission scopes useful? Are there any permission scopes you'd like to see and why those are important for your scenarios?

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

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:

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:

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.

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:

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.

The Azure AD Graph team is very pleased to announce the availability of the next version of Azure AD Graph REST API, api-version=1.6. There are no major changes from 1.5 to 1.6.

So you might ask why we’ve revved the version here. In March of this year, we made some changes to the 1.5 API, believing that these were non-breaking changes. However, due to an issue with a Graph client library dependency, this service side change caused a breaking change in the Graph client library (versions 2.0.5 and earlier). We were forced to roll back the service side change, and pause any API changes on the service side. More details can be found in this stack overflow question.

Since March, we’ve:

introduced more validation testing gates before releasing new client libraries and

introduced a fix in Graph client library version 2.0.8 that allows updates to the Graph REST API without breaking the client (by ignoring any unknown collections)

Now we’re releasing a new API version – api-version=1.6 – that will allow our team to release additional directory functionality and capabilities through the Graph REST API, without breaking any existing clients (2.0.6 and earlier). As usual, you can try it out through Graph Explorer.

A new Azure AD graph client library

As part of this update, we’ll also be releasing graph client library version 2.1.0. Versions 2.1.x will be tied to REST API version 1.6 (while graph client library 2.0.x will betied to REST API version 1.5).

We’ll be updating the graph client library on a regular basis to make new functionality (and bug fixes) available to developers who prefer to use a client library vs pure REST API calls.

You can find the latest .Net (portable) client library on nuget.org here.

Feedback

We’re always interested to hear what you think, so please let us know if you have any feedback or suggestions for the Graph API or client library.

You may have noticed that Graph Explorer looks a little different these days. We've made a few alterations and changes, together with a new improved UI, and we hope to put the source code on Github pretty soon. The main changes that you'll see are:

Graph Explorer requires users to consent to allow it access to their directory

It has autocomplete capability for entities (to see it click Use Demo Company, and click in the text box)

You can now press Enter/Carriage Return to execute request (small but great addition)

Additional response headers section – we can use this for troubleshooting issues you might have when running queries against Azure AD Graph API

There's now a JSON viewer

No support for displaying thumbnail photo

We hope you'll enjoy using the new version. We're looking to add some more improvements, like making appropriate responses navigable, and displaying thumbnail photo.

Let us know what you think and if you have any new suggestions.

]]>https://blogs.msdn.microsoft.com/aadgraphteam/2015/06/01/graph-explorer-gets-a-new-look/feed/1Announcing the preview of Graph Reports and Events APIhttps://blogs.msdn.microsoft.com/aadgraphteam/2015/05/15/announcing-the-preview-of-graph-reports-and-events-api/
https://blogs.msdn.microsoft.com/aadgraphteam/2015/05/15/announcing-the-preview-of-graph-reports-and-events-api/#respondFri, 15 May 2015 15:51:00 +0000https://blogs.msdn.microsoft.com/aadgraphteam/2015/05/15/announcing-the-preview-of-graph-reports-and-events-api/We’re pleased to announce that Activity and Events Reporting data is now available, in preview, through the Azure AD Graph API. You may have seen some of this information already surfaced through the Azure Management Portal, under the Reports tab in the Active Directory extension. These reports and activity logs are now also available to developers through the Graph API with this release. For more details, check out the MSDN documentation here: Azure AD Reports and Events (Preview)

Like other applications using the Graph API, access is available through requesting permission scopes to Graph API through the Azure Management Portal. To access reporting data, your application will need to either:

request the Read directory data delegated permission AND the user needs to be a company administrator, OR

in the case of application-only, the application needs to be given application permissions to Read directory data.

Example REST API calls

Here are a couple of examples for you, so you can see how easy it is to get this rich information. Note: since this is a preview feature, these queries are ONLY available using api-version=beta.

Pretty simple – but if you want to find out more, check out our simple Report API Sample to see how to get all the reports as well as to filter the reports on dateTime. We also have a Reporting API getting started guide for simple rest calls. Using only REST calls, this API can easily be integrated into SEIM tools such as splunk and arcsight.

Feedback

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

We wanted to point your attention to some great new documentation for Graph API that we've just lit up on MSDN here: https://msdn.microsoft.com/en-us/Library/Azure/Ad/Graph/api/api-catalog. Now you can interactively try out some of our operations (currently only on user and group entities, and the "me" alias) and see the requests and responses inline, right there within the online documentation!

What's more, you can even get code snippets for the operation in your favorite language. cURL anyone?

We've also moved our reference documentation to this new documentation platform, making it easier to see all of our entities and complex types all in one place.

We hope you like this change, and we'll be adding more operations entries for our other entities over time. Please let us know what you think!

]]>https://blogs.msdn.microsoft.com/aadgraphteam/2015/04/29/new-interactive-documentation-for-azure-ad-graph-api/feed/2Full Text Search Capabilities in Azure AD Graph API (preview)https://blogs.msdn.microsoft.com/aadgraphteam/2015/04/10/full-text-search-capabilities-in-azure-ad-graph-api-preview/
https://blogs.msdn.microsoft.com/aadgraphteam/2015/04/10/full-text-search-capabilities-in-azure-ad-graph-api-preview/#commentsFri, 10 Apr 2015 06:50:00 +0000https://blogs.msdn.microsoft.com/aadgraphteam/2015/04/10/full-text-search-capabilities-in-azure-ad-graph-api-preview/Advanced warning notice: The Azure AD Graph team will be shutting off this preview capability. As of September 19th 2016, this feature will no longer be available. We'd like to hear from you if you have been using this capability, and what you think about it. We are currently investigating some options around introducing this type of capability again at a future (unspecified) date.

The Azure AD Graph team is pleased to announce the public preview of full text search capabilities. Until now, searching AAD entities was limited to $filter searches and had a number of limitations developers found constraining. With this preview functionality we add more powerful search mechanisms to the AAD Graph.

What this enables

In this section we’ll talk about different scenarios that can be achieved using this new full text search capability, together with some example REST calls.

Using full text search

AAD Graph now has the ability to leverage a full text index to move beyond the limitation of only being able to search for words that appeared at the start of the property text and words which followed immediately after one another.

As an example, if you wanted to discover all the company discussion groups you might do a search for “Contoso discussions” across group name and description. However, using filter searches, you’d miss groups titled “Discussions about Contoso”, “Contoso Social Discussions”, “DL for Contoso Discussions” etc. This is not the case for full text searches where it will search the two tokens “Contoso” and “discussions” across all of the objects in scope.

To perform a full text search, you must be targeting either Users, Contacts, or Groups and you must use the api-version “beta”, then use the $search argument to pass your search text.

GET /contoso.com/users?api-version=beta&$search=search text

Searching across all fields at once

The default for $search will be to search across all indexed fields. This means it’s no longer necessary to form a query such as:

GET /contoso.com/users?api-version=1.5&$filter=startswith(displayName,'james') or startswith(givenName,'james')

Instead, you can simply make the query:

GET /contoso.com/users?api-version=beta&$search=james

NOTE: These searches are not identical. In this case the full text search would return a user with the name of “John James” as well as “James Doe”

Searching across specified fields

Even though the default for search is to evaluate all fields there are scenarios where it is useful to restrict the fields. This can be accomplished using the “searchable-fields” argument when making the search. For example you may want to search for all the users named James that are in building 2 but you don’t want to pull up users with 2 in another field:

GET /contoso.com/users?api-version=beta&$search=james+2&searchable-fields=displayName,physicalDeliveryOfficeName

Ordering by any property

Previously if you wanted to sort by a property that was the only property you could do your filtering with. Another valuable capability that also gets introduced is searching on one field but sorting on another.

To search for all users with James showing up on their user object but ordered by jobTitle, the following search can be performed:

GET /contoso.com/users?api-version=beta&$search=james&$orderby=jobTitle

Of course searchable-fields could be used to restrict the properties the $search is relevant for and it doesn’t have to contain jobTitle.

Paging

Previously filtering, sorting and paging through a single AAD Graph API REST request was not possible. However, paging is now possible in all types of search through the use of the $top and $skip arguments.

For example, you can fetch a page of 10 users containing “James”, ordered by job title:

GET /contoso.com/users?api-version=beta&$search=james&$orderby=jobTitle&$top=10

Then, subsequently use this query to get the next set:

GET /contoso.com/users?api-version=beta&$search=james&$orderby=jobTitle&$top=10&$skip=10

NOTE: Unlike regular Graph API calls, when using $top with full-text search, an @odata.nextLink will not show up in the response. For paging, you’ll need to use $skip.

Text-Mode

By default all terms in the search text must be contained in the object, for the object to be returned. However this can be controlled with the “text-mode” parameter. So if you want to simply ensure that any of the search terms match, you can set “text-mode” to “any”.

Using the “any” mode, a search for “John Doe” would return all the John’s and all the Doe’s.

GET /contoso.com/users?api-version=beta&$search=john doe&text-mode=any

More complex queries

+

AND Operator. James+developer would find all the objects with James and Developer.

|

OR Operator. James|Karl would find all the objects with James or Karl.

-

NOT Operator. James -developer would find all the objects with James which don’t have developer

Limitations

Read-Write Consistency

This full text search offering is made possible by an index separate from the main data storage. That means that changes made to the directory must replicate to the index. This generally happens in just a few seconds however it can lead to some inconsistencies when doing lots of edits and interactively performing searches expecting the edits you just made to be reflected.

NOTE: This has the consequence of, in certain race conditions, to return objects which used to match the search terms but no longer do. The search results will however always eventually converge with the data store and this behavior should be rare.

Object Limitations

Currently this full text search capability is limited to only Users, Contacts and Groups. Other objects types (Applications, Devices, etc.) may have support added to them depending on community feedback.

Suffix searches

Suffix searches suffer from a few problems:

Suffix searches have very poor performance especially when using only a few letters before the suffix operator. Suffix searches using only one or two characters are not recommended.

Suffix searches fail when the search text contains word breaking characters. If someone’s email address is James-Doe@contoso.com or James.Doe@contoso.com a search for James.D* or James-D* will not find these objects.

Paging

As noted earlier, unlike regular Graph API calls, when using $top with full-text search, an @odata.nextLink will not show up in the response. For paging, you’ll need to use $skip. We’ll look to rectify this in the future.

Upcoming additions

The following additions to search capability are being investigated. We welcome community feedback on which are the most valuable.

Multi-object search support

Currently only one object can be searched at a time. In the future we will provide the ability to search across multiple types of objects. This will allow you to write one query to give you a true people picking search capability (that does full text search across multiple objects like users and groups, ordering by display name and getting back paged results).

Performance Improvements

Performance improvements for search in general as well as specifically for suffix searching capabilities are being investigate.

Additional object type support

Adding the ability to perform searches for objects other than Users, Contacts and Groups.

Fuzzy Search

The ability to search with a fuzzy edit distance. This takes care of most types of misspellings (e.g. ‘Hames’ finds ‘James’).

Phonetic Search

The ability to specify a phonetic search so terms that sound alike can be returned (e.g. ‘John’ and ‘Jon’ could be returned with a phonetic search of ‘Jawn’).

Graph client library support

Currently full-text search is only available through the REST API. This feature would expose full-text search capabilities through the Graph Client Library

Feedback

We'd love to hear what you think about the new full text search capability, any issues you see and any suggestions you might have for improvements or new features and additions.

We wanted to provide a few details on our API versioning strategy and our contract with application developers who consume our APIs (and client libraries). This became a concern recently when a change on the REST API (addition of the new alternativeSignInNamesInfo collection on the User entity) lead to a break in our Azure AD Graph client library (see this Stack Overflow post). For this particular case, the Graph team did not envisage that this change would cause a break. However, it brought to light the importance of being very clear about our versioning contract with application developers.

API contract, versioning and breaking changes

Any breaking change to the API will result in an increment to the API version number to protect client applications. We may choose to increment the API version for non-breaking changes too (for example if we add some significantly large new capabilities).

NOTE: For Azure AD Graph API, you may notice that the addition of new JSON fields to responses does not constitute a breaking change. For developers that generate their own client proxies (like WCF clients) our guidance is that clients should be prepared to receive properties and derived types not previously defined by the Azure AD Graph API service. Although Azure AD Graph API is not yet OData V4 compliant (this is in our future plans), it still follows the guidance described in the Model Versioning section in the OData V4 spec.

We're also exploring the Azure Service Updates feed for promoting more visibility into Azure AD Graph API version changes.

API version lifetime

When we increment the major version of the API (for example from 1.5 to 2.0), we are signaling that all support for existing clients using previous 1.x or earlier versions will be deprecated. We will however continue to support these previous versions for a minimum of 12 months. Please see the Microsoft online services support policy for more details.

Introducing version=beta

We’re also introducing a brand new version – api-version=beta. This version of the Azure AD Graph API will provide you with an endpoint where you can try out our latest and greatest preview features, and provide the Azure AD Graph team with feedback. When our team believes that a preview feature is ready for GA, we will add that feature to the latest existing GA version (or if it constitutes a breaking change this would result in an incremented new version number). However, we make no guarantees that a preview feature will be promoted to GA.

For the beta version, we will try to avoid any breaking changes on this version as much as possible, but we will not guarantee it. Client applications using the beta version should expect breaking changes from time to time. Please see preview terms of use for more information.

We will also look to produce Azure AD Graph Client Library (preview) on top of the beta Graph REST API version. Alternatively you can use Vipr to generate your own client library if you so desire.

As ever - please let us know what you think, and if anything's unclear here.