Getting started with the Graph API with the Graph Explorer

___________________________________________________________________________________________________________________________

IMPORTANT ANNOUNCEMENT FOR OUR READERS!

AskPFEPlat is in the process of a transformation to the new Core Infrastructure and Security TechCommunity, and will be moving by the end of March 2019 to our new home at https://aka.ms/CISTechComm (hosted at https://techcommunity.microsoft.com). Please bear with us while we are still under construction!

We will continue bringing you the same great content, from the same great contributors, on our new platform. Until then, you can access our new content on either https://aka.ms/askpfeplat as you do today, or at our new site https://aka.ms/CISTechComm. Please feel free to update your bookmarks accordingly!

Why are we doing this? Simple really; we are looking to expand our team internally in order to provide you even more great content, as well as take on a more proactive role in the future with our readers (more to come on that later)! Since our team encompasses many more roles than Premier Field Engineers these days, we felt it was also time we reflected that initial expansion.

If you have never visited the TechCommunity site, it can be found at https://techcommunity.microsoft.com. On the TechCommunity site, you will find numerous technical communities across many topics, which include discussion areas, along with blog content.

NOTE: In addition to the AskPFEPlat-to-Core Infrastructure and Security transformation, Premier Field Engineers from all technology areas will be working together to expand the TechCommunity site even further, joining together in the technology agnostic Premier Field Engineering TechCommunity (along with Core Infrastructure and Security), which can be found at https://aka.ms/PFETechComm!

As always, thank you for continuing to read the Core Infrastructure and Security (AskPFEPlat) blog, and we look forward to providing you more great content well into the future!

__________________________________________________________________________________________________________________________

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.

clip_image002

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

clip_image004

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.

clip_image006

Once successfully logged in, you will see output similar to the following screenshot.

clip_image008

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.ActiveDirectory.User/@Element",
  "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