Getting Started with Azure Active Directory Graph API

Hello Everybody,

In this article we will discuss the concept of Azure Active Directory Graph API and how to start using Graph API.

In local active directory, when any application integrated with local AD want to look up for objects in the directory it used Lightweight Directory Access Protocol (LDAP) in order to perform the queries, LDAP is the protocol used to perform queries against local AD, modifying objects in AD, Adding and removing …etc. For example, if local exchange server wants to search for an object in active directory it will use LDAP protocol to achieve this. Also any other application which integrated with local AD will use LDAP to communicate with Active Directory.

So in general, LDAP is a query language with its special syntax that used to search and perform some operations in the directory such ass Add objects, Update Objects …etc.

To demonstrate the concept of LDAP, lets login to local active directory server and try to search for an object in our directory using LDAP queries, the simplest way to do that is to open Active Directory users and computers console, Right Click in the directory name and choose Find as appear below:

Now, change the find option to be “Custom Search” and click on Advance tab as appear below:

In “Enter LDAP query” field, we can enter our queries and click on Find Now button to get the result, for example if we write below LDAP Query and click on “Find Now” button:

LDAP Query to retrieve all groups in the directory:

(objectCategory=group)

We can see Cleary from above snapshot that the LDAP query get all groups in our directory.

Also, let’s try to get all objects with User type which their names begin with “MO”, to do that let’s execute below LDAP query:

(&(objectCategory=person)(objectClass=user) (cn=Mo*))

The result of the query will retrieve all users which their names starting with “Mo” as appear below:

So imagine that you have an attendance system in your environment, usually such these systems require user’s information, these systems usually configured to be integrated with local active directory to retrieve all employees’ information, in this case the attendance system most probably will apply the queries against local active directory using LDAP queries.

In azure Active Directory the story is different, LDAP was replaced with Graph API which can be used in order to execute queries against Azure Active Directory, Graph API provides programmatic access to azure AD through, Applications can use Graph API to perform Create, read, update and delete operations (CRUD) against Azure AD and get the result of queries in JSON format, so the applications should communicate with Azure AD using Graph API instead of LDAP protocol.

The general syntax of Graph API queries looks like below formula:

https://graph.windows.net/{tenant-identifier}/{resource-path}?[query-parameters]

Example on that Syntax:

https://Graph.Microsoft.net/AzureDummies.com/user?$filter=DisplayName eq “Ali Saleh”

Service Root: In Azure AD Graph API, the service root is always https://graph.windows.net.

Tenant identifier: This can be a verified (registered) domain name, in above example it’s our verified domain AzureDummies.com, we can also use .onmicrosoft domain if needed, It can also be a tenant object ID or the “myorganiztion” or “me” alias

Resource path: This section of a URL identifies the resource to be interacted with (users, groups, a particular user, or a particular group, etc.) In the example above, it is the top-level “users” to address that resource set. You can also address a specific entity, for example “users/{objectId}” or “users/userPrincipalName”.

Query parameters: ? separates the resource path section from the query parameters section. The Graph API also supports the following OData query options: $filter, $orderby, $expand, $top, and $format. The following query options are not currently supported: $count, $inlinecount, and$skip.

Note: at the end of the query you should specify the API version to be used, for example you should write above syntax in this way https://graph.windows.net/AzureDummies.com/users?api-version=1.6, but in our below examples we will not specify it since the web interface will use its API version implicitly.

To demonstrate the concept more, let’s navigate to https://graphexplorer2.cloudapp.net which is a web interface which will help us to execute Graph API queries against Azure AD, after open the web page just click on sign in label as appear below:

Enter a credential for a user with appropriate permission in the directory and click sign in button as appear below:

It will ask you to confirm the requested permission, click Accept button as appear below:

Just verify that the login successes as appear below:

Note: Graph Explorer site only support read (GET) queries, it’s not supported to execute other operations such as deleting objects, we can use https://graph.microsoft.io/en-us/graph-explorer in order to execute other operation which will be discusses in next lines.

Now, for example to get all details about all users in Azure AD we can run below query and click on the GET Button as appear below:

If we zoom out the result, we can see for example a user called “Ahmad Yasin” with his information as appear below:

Assume now we need to get all information about “Ali Saleh user, we can execute the GET query and specify the User Principle name in the query as appear below:

Also if we need to get the Job Title for “Ali Saleh” we can execute the GET query and specify the attribute we need to find it in the query as appear below:

Let’s assume we need to know the status of the password policy for the same user, we can execute below query:

Also we can execute other commands like Create, delete and update operations against azure AD, to demonstrate more, let’s navigate to other website https://graph.microsoft.io/en-us/graph-explorer which will give us the ability to execute more operations, let’s sign in in the page with our tenant privileged account as appear below:

Let’s try to get the information about “Mohammad Saleh” user by executing GET query as appear below:

Let’s double confirm that the user exists in our Azure AD by looking for it in office 365 users as appear below:

Now, let’s try to remove the user by executing below DELETE command:

To verify that the user was removed, let’s try to execute GET query as appear below:

We can be noticed from above snapshot that the user no longer exists, to double confirm that the user was removed, let’s go back to office 365 users, we will see now that the user appears in the deleted user’s container as appear below:

Note: This Article will not discuss the development side using Graph API, It’s Just to demonstrate the general concept of accessing Azure AD using Graph API, for full information about Graph API concepts and references, follow Microsoft Article: https://msdn.microsoft.com/en-us/library/azure/hh974476.aspx

As a conclusion, Application can be integrated with Azure Active Directory using Graph API in the same manner of integrating Applications with local active directory using LDAP.

Ahmad Yasin (MCSA office 365, MCSE : Messaging, Azure Certified)

Ahmad Yasin is a Microsoft Cloud Engineer and the Owner & publisher of AzureDummies blog. He also holds many certificates in office 365 and windows azure including Developing Microsoft Azure Solutions, Implementing Microsoft Azure Infrastructure Solutions and MCSA office 365.

Find Ahmad at Facebook and LinkedIn.

 

Leave a Reply

Your email address will not be published. Required fields are marked *