Azure Active Directory Graph – What’s in it for an app developer?

  • Article

As we mentioned in the last post, Windows Azure Active Directory (AAD) Graph service lets an application developer access and manipulate the information in Azure Active Directory. But why should an application developer care about this information? Let’s start by looking at Windows Active Directory and drill down to the Graph service for Azure Active Directory which this blog will focus on.

 

What is Active Directory (AD)?

Active Directory provides authentication and authorization for users and computers in Windows Networks. For example, one of the things AD does when user logs in is it verifies that the user name and password are correct. AD also has a lot of interesting information about the user like the information you would find in an address book and the organizational information (like who he reports to, who are his direct reports) etc. This information is used to authorize user when he tries to access resources on the network. This is a very high level overview of Active Directory. There is plenty of information on MSDN, Wikipedia etc. that talks about AD in great detail.

 

What is Windows Azure Active Directory?

Windows Azure Active Directory(AAD) provides identity management and access control capabilities for cloud applications including Microsoft Cloud applications like Windows Azure, Office 365, Dynamics CRM etc. and also for 3rd party cloud applications. Like Windows Active Directory, Azure Active Directory also provides authentication services by verifying the user name and password for the users when they login. Like AD, it also has a lot of interesting information about the user like the information you would find in an address book and the organizational information (like who he reports to, who are his direct reports) etc. In addition to providing the authentication services using the credentials it stores, AAD also can authenticate users with their on premise Windows Active Directory credentials.

 

Using Azure Active Directory in Enterprise Cloud Applications

There are several advantages in integrating your application with AAD for authentication and authorization needs. Given that AAD is leveraged by Microsoft cloud services, you have the ability to provide your application users with a single sign on experience across your application and services like Office 365, Windows Azure etc. You can manage access to your application based on roles and policies that you can set up in AAD. AAD not only can help you when building Line of business (LOB) cloud applications for your organization but also when building enterprise cloud applications that you plan to sell to other organizations. Since AAD is a multi-tenant service, the authentication and access control mechanism that you build into your application can be designed in such a way that it can be used with any tenant or organization provisioned in Azure Active Directory. Given that a lot of organizations are already using Office 365, it is a great convenience for these organizations if they can reuse their information in AAD with 3rd party cloud applications.

There is a ton of useful information in Azure Active Directory that the application developers can use for many different purposes. But how do you access this information? This is where AAD Graph come into the picture.

 

Azure Active Directory Graph

The AAD Graph Service lets you access the information in the AAD through a simple RESTful service. It uses the OData protocol to implement the RESTful service. Understanding some of the basics of RESTful services and the OData protocol is important to gain a solid understanding of how to work with AAD Graph service.

 

What is a RESTful Service?

There is plenty of information about REST on MSDN, Wikipedia and other web sites. Here is a pretty short and high level overview of RESTful services.

Representational State Transfer( REST ) is an architectural style with a set of rules that can be applied when building something( from MSDN article on REST and WCF Services ).

A RESTful service exposes data as a set of Resources on web and follows these rules:

  • Is implemented using HTTP
  • Different operations like Read, Create, and Delete etc. are supported via HTTP methods like Get, Post, Delete etc.
  • The set of resources exposed by the service have a well-defined set of URIs.
  • Data encoding is in Xml or JSON formats.
  • The API is hypertext driven i.e. the response will include all the information needed to interpret it.

 

What is OData?

OData is a web protocol for querying and updating data via RESTful services. It helps you expose data over the web as a set of resources which can be accessed and manipulated using HTTP methods.

Let’s look at some of the important rules/principles for services implemented using the OData protocol:

  • The root of the service always exposes a service document. Service document exposes the list of all resource collections available in the service.
    • For example, https://services.odata.org/OData/OData.svc is the service document for a sample OData service. As you can see, Products, Services and Suppliers are the resource collections exposed by this service.
  • It defines a set of conventions to define the URIs for the resources. For example, the URI for a resource set exposed by the service has the URI of the format <ServiceDocumentURI>/<ResourceSetName>. Based on this convention, you can construct the URI for “Products” Resource Set which would be https://services.odata.org/OData/OData.svc/Products.
  • You can use HTTP operations like GET, POST, Delete etc. to support retrieving, creating, updating data exposed by the service. For example, doing a HTTP Get on the following URL: https://services.odata.org/OData/OData.svc/Products(1) will retrieve the content of the resource in the Products Resource set with Key value ‘1’.
  • Defines a set of query options that can be represented as HTTP Request parameters and are used to perform advanced query operations like Filter, Top etc. Here is an example of a query that filters the Categories Resource set for Resources whose name equals ‘Beverages’: https://services.odata.org/OData/OData.svc/Categories(1)?$filter=Name eq 'Beverages' .

 

So we have described that a RESTful service built using OData protocol can be accessed and manipulated using HTTP operations. We also mentioned that AAD Graph is one such service. In the next blog post, let’s do a deep dive into various operations you can do against the AAD Graph service using HTTP and also look at the responses we get back.