OakLeaf Systems: A Guided Tour of the Graph API Preview’s Graph Explorer Application

Thursday, July 19, 2012

A Guided Tour of the Graph API Preview’s Graph Explorer Application

The Graph API Preview’s Graph Explorer application for Windows Azure Active Directory (WAAD) reads the graph of the specified WAAD tenant (company), including its Users and their Managers, which WAAD exposes in OData v3 format.

Note: For more information about WAAD, including how to obtain authorization credentials for an Office 365 subscription, see my A Guided Tour of the Windows Azure Active Directory Developer Preview Sample Application post, updated 7/19/2012.

The Graph API’s Graph Explorer is modeled after Facebook’s Graph API Explorer application:

Edward Wu presented Directory Graph API: Drill Down at TechEd North America 2012 on 6/14/2012. From the video archive’s description:

This session introduces the new Directory Graph API, a REST-based API that enables access to Windows Azure Active Directory (Directory for Office 365 Tenants and Azure customers). We review the data directory model, the Graph API protocol (based on Odata V3 protocol), how authentication and authorization is managed, and demonstrate an end-to-end scenario. We walk through sample code calling the Directory Graph API. A roadmap is also reviewed.

MSDN’s Windows Azure Active Directory Graph topic provides detailed documentation for the Graph API.

The WAAD graph’s schema is defined by the metadata resource at https://directory.windows.net/$metadata:

Note: The preceding screen capture displays about 10% of the total metadata lines.

Following are detailed instructions for using the Graph Explorer to display a raw OData feed for the sample OakLeafSystems tenant described in the A Guided Tour of the Windows Azure Active Directory Developer Preview Sample Application post:

1. Launch the Graph Explorer, which runs under Windows Azure, at https://graphexplorer.cloudapp.net/, click the Use Demo Company link to add GraphDir1.OnMicrosoft.com/ to the URL, and click the Get button to display a list of the available EntitySets (collections):

2. If you have a Office 365 subscription, click the Sign Out button to return to the default resource, and add its domain name, oakleaf.onmicrosoft.com for this example, as a suffix to the default URL:

3. Add a virgule (/) and one of the of the EntitySet names, such as TenantDetails, as a query suffix to the resource text box (look ahead to step 4) and click the Get button to open the resource page with the Company text box populated. Copy the Principal Id and App Principal Secret values from the PowerShell script’s command window (see the A Guided Tour of the Windows Azure Active Directory Developer Preview Sample Application post) and paste them into the Principal Id and Symmetric Key text boxes, respectively:

Note: You should keep the Principal Id value confidential; a default Symmetric Key/App Principal Secret value applies to all Preview demo logins.

4. Glick the Log In button to display the query results for the selected EntitySet, TenantDetails for the Company ObjectType:

Note: The updated Office 365 AssignedPlans collection includes a ServiceInstance for AccessControlServiceS2S/NA, in addition to the standard three items for Exchange, SharePoint and Lync.

5. Replace URL’s TenantDetails query suffix with Roles and click Get to display the six built-in administrative roles, the first of which is shown here:

6. Replace URL’s TenantDetails query suffix with Groups and click Get to display the built in groups, the first three of which are shown here:

Note: The DirectReports’ uri property points to a collection of Users with a ReportsTo property value of Manager.

7. You can execute queries to display a specific user, group, role or the like by using the OData query syntax explained in the Graph API documentation’s Windows Azure AD Graph Common Queries section.

A Sample Application for Azure Active Directory Graph API (RESTful API) C# Windows Azure ASP.NET MVC Web Role application is available for download. From the app’s About page:

This is a sample MVC application showing how to access the preview of the "Windows Azure Active Directory Graph API”, which is a new RESTful interface allowing customers to build applications to access their Windows Azure AD tenant’s directory data.

Here’s a capture of the Home page: