First published on TechNet on Mar 29, 2015
Hi Folks. Lakshman Hariharan here with a post on a cool tool from our good friends on the Azure team called Graph Explorer. In a nutshell, the Azure AD Graph API provides programmatic access to Azure AD through REST API endpoints. Applications can use the Graph API to perform create, read, update, and delete (CRUD) operations on directory data and objects. For example, the Graph API supports the following common operations for a user object:
· Create a new user in a directory
· Get a user’s detailed properties, such as their groups
· Update a user’s properties, such as their location and phone number, or change their password
· Check a user’s group membership for role-based access
· Disable a user’s account or delete it entirely
Since I am not a programmer even if one were to apply the most generous interpretation of the word, this feature called Graph Explorer that I came across recently peeked my interest. Graph Explorer, as the name suggests, allows you to explore or browse your Azure AD with absolutely no programming skills required. Several blogs abound discuss what Graph Explorer is, so I intend to use this post to show you how you can, if you have an Azure AD tenant setup, start using Graph Explorer. The post is broken down into four steps.
Step 1: Log in to your Azure AD tenant using Azure Active Directory Powershell
Step2: Create the Service Principal (MsolServicePrincipal) and allow access to read and modify data
Step 3: Login to Graph Explorer
Step 4: Run queries using Graph Explorer
So that being said, let’s get started. Before you can follow along this step by step, here are few things you will require
1. An online Azure AD tenant setup with at least a handful of users populated either via DirSync or AADSync from your on-premises Active Directory environment.
2. An online Service Principal (MsolServicePrincipal) that has permissions to access your online Azure AD tenant.
Step 1: Log in to your Azure AD tenant using Azure Active Directory Powershell
My online Azure AD tenant is called lhazure.com so I used the Connect-MsolService cmdlet to connect and authenticate to Azure AD using an account that is a Global Administrator
Step2: Create the Service Principal (MsolServicePrincipal) and allow access to read and modify data
a. Once logged in using an account that is a Global Administrator, execute the following PowerShell cmdlet to create the new Service Principal
New-MsolServicePrincipal -DisplayName GraphExplorer -Type symmetric
This will result in something similar to the following screenshot
Since I didn’t specify a value for the symmetric key, one was automatically generated for me.
Important: Make a note of this key and the AppPrincipalID because you will need it to log in to Graph Explorer. Also make a note of the ObjectID since you will need it to provide the Service Principal rights to Azure AD.
b. Execute the following cmdlet to give the Service Principal you created in the previous step rights in Azure AD. At the risk of stating the obvious, replace the value for RoleMemberObjectID with the value of the ObjectID created by you. This should return a successful result.
Add-MsolRoleMember -RoleName "Company Administrator" -RoleMemberType ServicePrincipal -RoleMemberObjectId ee4d6241-9b84-4a64-af08-b7d429090497
Step 3: Login to Graph Explorer
Open Internet Explorer and navigate to https://graphexplorer.cloudapp.net . This will result in landing at the page depicted in the screenshot below
Under “Resource” , enter the following, replacing <yourAzureADTenant> with the actual name of your Azure AD tenant. In this case I am interested in getting a list of users,
https://graph.windows.net/<yourAzureADTenant>/users?api-version=2013-04-05
When replaced with my Azure AD tenant of lhazure.com it looks like the following screenshot
Now click “Get” on the right of the Resource URL.
This will bring you to the login prompt where you will enter the AppPrincipalID and Symmetric key generated in Step 2.As you can see, you also have the option of using the Demo Company as well but in this case I am demonstrating using an actual Azure AD tenant.
Once successfully logged in, you will see output similar to the following screenshot.
Step 4: Run queries using Graph Explorer
For a list of common Graph API queries refer to this article. Now let’s walk through a few examples using lhazure.com.
In this first query I am interested in seeing the properties of a user named John Doe that has a UserPrincipalName of johndoe@lhazure.com . So I enter the following request:
https://graph.windows.net/lhazure.com/users/johndoe@lhazure.com?api-version=2013-04-05
This results in the following output. Note some of the properties highlighted.
{ "odata.metadata": " https://graph.windows.net/lhazure.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirec... ", "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User", "objectType": "User", "objectId": "1c2260b0-41a6-4e32-a5ea-eb7f4ce46103", "accountEnabled": true, "assignedLicenses": [], "assignedPlans": [], "city": "Fictionland", "country": null, "department": null, "dirSyncEnabled": true, "displayName": "John Doe", "facsimileTelephoneNumber": null, "givenName": "John", "jobTitle": null, "lastDirSyncTime": "2015-03-07T17:01:32Z", "mail": null, "mailNickname": "johndoe", "mobile": null, "otherMails": [], "passwordPolicies": null, "passwordProfile": null, "physicalDeliveryOfficeName": null, "postalCode": null, "preferredLanguage": "Fictional Language", "provisionedPlans": [], "provisioningErrors": [], "proxyAddresses": [], "state": "FI", "streetAddress": "123 ABC Lane", "surname": "Doe", "telephoneNumber": null, "usageLocation": null, "userPrincipalName": "johndoe@lhazure.com"
}
If I am interested in only returning the Street Address for John Doe I use the following query
https://graph.windows.net/lhazure.com/users/johndoe@lhazure.com/manager?api-version=2013-04-05
{ "odata.metadata": " https://graph.windows.net/lhazure.com/$metadata#Edm.String ", "value": "123 ABC Lane"
}
If I am interested in querying what groups John Doe is a member of then I run the following query. As you can see John Doe is a member of the group All Full Time Employees.
https://graph.windows.net/lhazure.com/users/johndoe@lhazure.com/memberOf?api-version=2013-04-05
{ "odata.metadata": " https://graph.windows.net/lhazure.com/$metadata#directoryObjects ", "value": [ { "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group", "objectType": "Group", "objectId": "7ffb6db2-e41c-4b67-8170-f959a1d3f2ca", "description": null, "dirSyncEnabled": null, "displayName": "All Full Time Employees", "lastDirSyncTime": null, "mail": null, "mailNickname": "06f92982-41f9-4c96-b6a8-865ed4e2b82c", "mailEnabled": false, "provisioningErrors": [], "proxyAddresses": [], "securityEnabled": true } ]
}
Well, that’s it from me, for now. Hope you find this post as useful and the feature as cool as I did. Happy exploring...
Lakshman Hariharan