In Azure Active Directory (AAD) there is a Graph API. This is the main API to access AAD. The idea of a Graph API is not entirely new. The one provided by Facebook is already well established. But what is this really about and why does AAD provide such an API?
First of all, I neither like the term “Graph API” nor “API” itself very much. Both are, from my perspective, far too technical. They are fine for people with a good background in mathematics and computer science, but not for typical business people. A graph is a mathematical concept describing nodes and their connections. The structure of AAD can be understood as a graph. To navigate this graph, there is an API (Application Programming Interface) – the Graph API.
So the AAD Graph API is the interface for navigating the content of AAD (walking the tree, or, more correctly, the graph) and accessing (and creating and manipulating) the information stored therein. Developers can perform CRUD (Create, Read, Update, Delete) operations through REST (Representational State Transfer) API endpoints when developing applications such as web applications and mobile apps – as well as more conventional business processes.
It comes as no surprise then that the Graph API is REST-based. REST is the de facto standard for new types of APIs. It is rather simple to use, especially when compared with traditional methods for directory access such as the LDAP C API (yes, it always depends on what you compare something with…).
The Graph API of Azure AD provides a broad set of standard queries that can be used to retrieve metadata information about the tenant’s directory and its data structure, but also about users, groups, and other common entities. Apart from these standard queries, there are so-called differential queries that allow developers to request only the changes that have happened on the result set of the query since the previous query run. This is very interesting for applications that need to synchronize AAD and other data stores.
Access to the Graph API is done in two steps. The first one is the authentication (based on tenant-ID, client-ID and credentials), which is done against the Windows AAD authentication service. The authentication service returns a JWT Token. This token then can be used for running Graph API queries. The Graph API relies on an RBAC (Role Based Access Control) model. It authorizes every request and returns the result set if the authorization has been successful.
Overall, the Graph API is a simple yet powerful concept for accessing content of the AAD. It is the successor to traditional approaches for directory access such as LDAP with its rather complex structure (which is simplified by ADSI, ADO .NET, etc.). Being based on REST, it is a familiar approach for web developers. There is a lot of information already available at the MSDN (Microsoft Developer Network) website.
From the perspective of a non-developer, the most important thing to understand is that it is far easier than ever before to build applications that rely on the AD – or, more particularly, on the AAD. All the information about the employees, business partners, and customers that organizations may hold in the AAD in future is accessible through the Graph API for new types of applications, from integration of that information into business processes to simple mobile apps providing, for instance, customer information out of the AAD. This is done in a secure way, based on the built-in security concepts of AAD such as the RBAC model. Graph API is one of the things that moves AAD from a purpose-built Directory Service (such as the on-premise AD) to a platform that allows you to flexibly connect your enterprise – the users, the things, the applications.