Announcing the new version of the Graph API: api-version=2013-11-08

We're excited to announce the next version of the Graph API, api-version=2013-11-08 is now available. There are several updates that can be useful for your applications, and enable some new scenarios.

The major updates in this release include: 

  • Support for provisioning Federated users
  • User License assignment
  • Support for adding multiple members to a Group
  • Managing a Group's Owner
  • Sorting Groups by their Display Name property
  • Additional Differential Query features

1. Provisioning Federated Users, by exposing a new user property: immutableId

We now expose a new user property called “immutableId” through the Graph API. What is the significance of this property?  It is used to associate the on-premises user object account to the cloud user hosted in Azure Active Directory – for example, if you have an on-premise directory, and the user object from that directory has an identifier GUID with a value of “9c5923e9-de52-33ea-88de-7ebc8633b9cc", then the Azure AD User object can store this value in its immutableId property (stored as a string). The immutableId is used to link the on-premises account identity with the Azure AD account identity.  Note: the immutableId value cannot contain spaces or the $ symbol.

Note: customers using the Microsoft DirSync tool, will automatically have sync’ed Azure AD Users’ immutableId property populated – DirSync writes this value as the base64 encoded value of the on-premises object Guid.  Application should store the value that meets the requirements of their federated identity service provider

Here’s an example GET call, requesting only a user’s immutableId property: 

GET https://graph.windows.net/contoso.com/users/Adam@contoso.com/immutableId?api-version=2013-11-08

RESPONSE (in JSON):   {   “value”:”6SNZnFLe6jOI3n68hjO5zA==”   }

If you are creating an Azure AD User, and are using a federated domain for the User’s userPrincipalName property, then you must specify a value for the user’s immutableId property – for example, this is the POST operation to create a new user, assigning @Fabrikam.com to the user’s userPrincipalName, which is configured as a federated domain.

Creating a New User using a federated  domain “Fabrikam.com”

POST

https://graph.windows.net/Contoso.com/users?api-version=2013-11-08

HEADERS:

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


 {        "accountEnabled":true,    "userPrincipalName":Derek@Fabrikam.com,    "displayName":"Derek ",      "mailNickname":"Derek",

     "passwordProfile":{ "password":"placeHold3r$", "forceChangePasswordNextLogin":false},     “immutableId”: “6SNZnFLe6jOI3n68hjO5zA==”

 }

 HTTP RESPONSE: 201 Created

 NOTE: in the above example, a password is required as part of the POST user creation call, but is not used because the User is using a Federated identity.

In this new API version, we have also exposed a new user property, userType.  This is a string value that can be used to allow tenants to classify the types of users within their organization.  For example, regular employees can be identified by userType =  “Member”,  and guest accounts associated with vendors, consultants or temporary workers, could be have userType = “Guest” .

 2. Support for User Licensing

This action was first available under a preview version (api-version=2013-04-10-preview) and is now officially supported in the “2013-11-08” release.  This method allows assignment and removal of a subscription for any provisioned user account. For example, here’s an initial license assignment of the Enterprise Office Sku, which contains SharePoint Online, Lync Online and the Exchange Online service plans.

POST 

https://graph.windows.net/contoso.com/users/adam@contoso.com/assignLicense?api-version=2013-11-08

HEADERS

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


 {  "addLicenses":[{"disabledPlans":[ ],"skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"}],  "removeLicenses":[ ]

 }

 HTTP RESPONSE:    200 OK

 

Here’s an example of updating a User’s license by disabling specific plans.  In this example, there are 2 disabledPlans (SharePointOnline and LyncOnline"), leaving only the Exchange Service Plan.

Select User License Assignment

POST

https://graph.windows.net/contoso.com/users/adam@contoso.com/assignLicense?api-version=2013-11-08

HEADERS

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


{   "addLicenses":[  { "disabledPlans":  [”5dbe027f-2339-4123-9542-606e4d348a72”,                                                            “0feaeb32-d00e-4d66-bd5a-43b5b83db82c” ], 

                             "skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"                             }  

                          ],   "removeLicenses":[ ]

 }

HTTP RESPONSE:   200 OK

 

Finally, here’s how to remove the license from the user.

Remove User License Preview

POST 

https://graph.windows.net/contoso.com/users/adam@contoso.com/assignLicense?api-version=2013-11-08

HEADERS

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


 {

  "addLicenses":[ ],  "removeLicenses":["6fd2c87f-b296-42f0-b197-1e91e994b900"]

 }

HTTP RESPONSE:   200 OK

 

How do you get the subscription Sku Id and the plan ids?  These can be read from the tenant object, by calling GET https://graph.windows.net/contoso.com/subscribedSkus
which will return the subscriptions available for the tenant – this includes the SkuId and servicePlans Id’s under the Sku. Availability of subscriptions can be calculated from the “consumedUnits” property and values
from “prepaidUnits” complex property, which includes counts of units that are “enabled”, “suspended” and in “warning” states.  You can view this using the https://GraphExplorer.cloudapp.net demo – select
“Use Demo Company”, and execute this query: https://graph.windows.net/GraphDir1.OnMicrosoft.com/subscribedSkus?api-version=2013-11-08

 3. Adding Group Members operation can now support multiple member objects in the same request.  

We have always allowed adding a single object to a group, but we now support multiple objects being added to a group in one call.  The example below adds two new users to a group.  NOTE: The maximum allowed number of links to add in a single POST/PATCH request should be kept to 20 or below.  Attempts to add a higher number of links can result in a failure response.

Update Group or Role membership

PATCH

https://Graph.windows.net/contoso.com/groups/02a8a087-a371-43f9-94df-cf0f654de307?api-version=2013-11-08

HEADERS

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


 {

   "members@odata.bind":

   [  

          "/contoso.com/users/09f8c01f-53cd-466f-9d2e-b7fb6a77b119",                 "/contoso.com/users/2ac58744-e872-49fa-bfb2-d0ff8c0d5750"

   ]

 }

HTTP RESPONSE:   204 No Content

 Note: Removing multiple members is not supported at this time.

 

4. Managing Group Owners  

How do you find a Group’s owner?  Easy - the following will return the Group's owner: GET https://Graph.windows.net/contoso.com/groups/02a8a087-a371-43f9-94df-cf0f654de307/owners?api-version=2013-11-08

The following will return the group object, and the owner objects in one call: https://Graph.windows.net/contoso.com/groups/02a8a087-a371-43f9-94df-cf0f654de307?$expand=owners?api-version=2013-11-08

And to assign an owner to a Group, the following POST operation can be executed:

Update a Group’s Owner

POST

https://Graph.windows.net/contoso.com/groups/02a8a087-a371-43f9-94df-cf0f654de307/$links/owners?api-version=2013-11-08

HEADERS

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

BODY


{

   "url":  "https://graph.windows.net/contoso.com/users/88478020-a5b2-4176-b720-838af8dee190"

}

RESPONSE: 204 No Content

 And with other links, you can also find out what objects are owned for a User: 

GET https://graph.windows.net/contoso.comt/users/adam@contoso.com/ownedObjects&api-version=2013-11-08

Or retrieve the user and the user's owned objects in one call: GET https://graph.windows.net/contoso.comt/users/adam\@contoso.com?$expand=ownedObjects&api-version=2013-11-08

5. Sorting lists of Groups by display name

We now allow your app to specify sorting by the Group’s display name property. For example: GET https://graph.windows.net/contoso.com/groups?$orderby=displayName?api-version=2013-11-8.  And in case you missed it in my previous blog post, you can specify sort order for user lists, by either the displayName or userPrincipalName property. 

6. Additional Differential Query features

Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls. This option is enabled by setting the header ocp-aad-dq-include-only-changed-properties to true as shown in this example.

 

GET

https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….

HEADERS

ocp-aad-dq-include-only-changed-properties : true

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….

Response: 200 OK

For example if only the “displayName” property of user has changed.  The returned object would be similar to this:

{     

          "displayName" : "AnUpdatedDisplayName",

         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",

         "objectType" :  "User",

          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"

},

Differential Sync Support to Sync from “now” - a special header can be specified, requesting to only get an up-to-date deltaToken, this token can be used in subsequent queries, which will
return only changes from “now”.  Here’s the example call:

GET

https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…

HEADERS

ocp-aad-dq-include-only-delta-token: true

Content-Type: application/json

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….

Response: 200 OK

The response will contain the deltaLink, but will not have the changed object(s), similar to this:

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

We’ll dive into Differential Query calls in much more detail in the upcoming posts.

Give Use Feedback

We will be updating our sample applications to show some of the above mentioned features in the new version: https://msdn.microsoft.com/en-us/library/hh974459.aspx and in an upcoming post, we will include code snippets showing how to use these new capabilities.

Please let us know if the new features are useful, and let us know what other Api's will be useful for your scenarios.  Leave a comment or your questions on this Post.

Thanks, Edward

Azure Active Directory Team

Microsoft Corp