0.9 Version of Azure Active Directory Graph now available!

  • Article

We have recently released 0.9 version of the Azure Active Directory Graph Service. The update includes some key improvements but it also comes with some significant breaking changes. We have just updated the .Net MVC Sample to work with the 0.9 version of the Service. As part of the sample, there is a thin helper library which includes the Service Reference for 0.9 version and includes some helper methods for setting up the required headers, query parameters etc.

Changes included in 0.9 Version of the Graph Service

  • Change in how you specify the Graph service version: Until 0.8 version of Graph service, it was required that the Version being targeted be specified as a Request Header. For 0.8 version, the header looked like ‘x-ms-dirapi-data-contract-version:0.8’ . Starting with 0.9 version of the service, you need to specify the version via a Request parameter. For example, https://graph.windows.net/graphdir1.microsoft.com/users?api-version=0.9.
  • Support for Key as Segment feature: The way you would have requested a User with a particular UPN previously would be to specify the UPN with in parenthesis. An example of the previous syntax: https://graph.windows.net/graphdir1.onmicrosoft.com/users(‘Adam\@GraphDir1.onmicrosoft.com’) . We received significant feedback that the URL syntax is not intuitive and it would be nicer if the UPN value (or the Key value) be specified as another segment in the URL. We are happy to inform that this support is included in the 0.9 version. Now you can specify the same request using the following syntax: https://graph.windows.net/graphdir1.onmicrosoft.com/users/Adam\@GraphDir1.onmicrosoft.com.
  • Camel casing of Properties, Collection names etc.: All the property names, EntitySet/Collection names have been changed to use Camel casing instead of the Pascal casing. So previously if the property name was ObjectId, it will be objectId in 0.9 version.
  • New JSON formats: We have started supporting three different formats of JSON with this version - Verbose, minimal metadata and no metadata (which in turn have been introduced by WCF Data Services). In the next version of the Service, we will make JSON - minimal metadata the default format but if you want to start using it now, you can do it by passing in the accept header with the value: ‘application/json;odata=minimalmetadata’. If you want to see how the response looks in this format, you can try it in Graph explorer which has been changed to use this format by default.
  • Support for Password Reset Bypass on Next Login: Password property has changed to being a complex type with two primitive properties. The complex property name on User has the name ‘passwordProfile’ and it has two primitive properties - password and a boolean property - forceChangePasswordNextLogin which is useful when you want to set or unset the policy of a User being forced to change the password on first login for a particular user.
  • Collections for Subtypes( users, groups etc.) missing in .Net generated proxy class and $metadata: OData does not have good support for exposing different top level collections for types belonging to the same inheritance hierarchy like directoryObjects, users, contacts etc. We tried to work around this in the service layer but this was leading to various classes of bugs. In order to have a clean service implementation, we have removed these collections from the $metadata and thus you won’t see them in the generated proxy. If you want to access the users collection, you can access them by using code like the following: return this.directoryObjects.OfType<User>() as DataServiceQuery<User>; . While we don’t support these collections( users, groups etc.) in $metadata, we do support hitting the Service with the specific collections without any problem. So the following HTTP request is still supported: https://graph.windows.net/graphdir1.onmicrosoft.com/users/Adam\@GraphDir1.onmicrosoft.com. On the Service side, we rewrite the request to https://graph.windows.net/GraphDir1.onmicrosoft.com/directoryObjects/$/Microsoft.WindowsAzure.ActiveDirectory.User/ Adam@GraphDir1.onmicrosoft.com which is the same as the HTTP request produced by the OfType Linq query.
  • WCF 5.2 or above tools needed to generate the Proxy: Because of the support for specifying the Key as segment, you need to regenerate the proxy if you want to target 0.9 version of the Schema. You can get the latest WCF tools from here.

As you can see, there are some significant changes in 0.9 version of the Service. If you hit any issues in upgrading your application to use 0.9 version, do let us know and we will be happy to help.