1. Consent is required one-time only per app, and is good across all devices for the same app, which was not the case previously.
2. 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.
3. 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?

1. Admins can now consent for mobile client apps on behalf of their organization.
2. The mobile application will now appear in the Azure Management Portal applications list.
   1. The app dashboard shows app usage
   2. Admins can apply policy for the app (conditional access and assigning the app to users to control access)
3. 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?

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. 

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:

1. We've restricted the "Read and write directory data" permission so that it no longer allows the application to reset other user passwords.
2. 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

To go with this release, we've updated our Azure AD Graph API permissions topic.  This topic goes into greater detail on all our permission scopes, describing:

• 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:

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:

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:

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:

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:

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:

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:

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.

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:

1. introduced more validation testing gates before releasing new client libraries and
2. 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.

We will document the version changes through our regular MSDN documentation channels in our versioning document, as well as within our interactive reference documentation.

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 be
tied 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:

1. Graph Explorer requires users to consent to allow it access to their directory
2. It has autocomplete capability for entities (to see it click Use Demo Company, and click in the text box)
3. Support for /me and /myorganization aliases
1. https://graph.windows.net/me
2. https://graph.windows.net/myorganization/users
4. You can now press Enter/Carriage Return to execute request (small but great addition)
5. Additional response headers section – we can use this for troubleshooting issues you might have when running queries against Azure AD Graph API
6. There's now a JSON viewer
7. 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.

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.

Viewing the list of reports

Viewing a specific report type

To view data in a specific report type, query /reports/<reportName>

To view a report type by a date range

Most datetime fields are filterable. Use $filter OData querying format to query different intervals. For example:

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.

Get rolling and rocking soon. Analyze activity logs to protect your users and optimize your app purchase and usage.

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! 

What this enables

Using full text search

Searching across all fields at once

Searching across specified fields

Ordering by any property

Paging

Text-Mode

More complex queries

Limitations

Read-Write Consistency

Object Limitations

Suffix searches

• 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

Upcoming additions

Multi-object search support

Performance Improvements

Additional object type support

Fuzzy Search

Phonetic Search

Graph client library support

Feedback

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).  

So, what constitutes a breaking change?

1. Removing or Renaming APIs or API parameters
2. Changes in behavior for an existing API
3. Changes in Error Codes & Fault Contracts
4. Anything that would violate the Principal of Least Astonishment

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.