Intune

Using Graph Explorer with Intune

In this article we are going to discuss the significance of Graph Explorer and how the same can be used with Intune.

My name Saurabh Sarkar and I am an Intune engineer in Microsoft. I have a YouTube channel and you can subscribe to the same to learn more about Microsoft Intune.

The entire demonstration of this article can be found in my below video:

Background:

I would like to explain the usage of Graph Explorer and the terminologies involved using the below analogy-

As shown in the figure, lets say that we have-
#A user who wishes to access some data.
#The user is surrounded by a fence
#The data he wishes to access is inside a building
#The Building has some windows/holes in it.
#The user uses a Rod/Pipe/Tunnel which goes from the fence to the Window.
#From this pipe he can send anything inside of the Window in the building or can see whats there on the other side of the window.

Now with this analogy in mind:

#User – Person who wishes to access the data

#Fence – Graph Explorer tool

#The pipe/rod – REST API calls

#The Windows- The APIs exposed

#Graph is the fence is the medium via which we are making the API calls.
API: Application Programming Interface
When we make an app, we expose some APIs. APIs are exposed so that a developer can see the data/modify the data/ consume the data.

API is a medium via which we are reading/change/modify consume the data
Using Graph Explorer we do that by making a REST API call.

REST(Representational State transfer) is actually a protocol on which the GRAPH works.

Diagram:

Now lets take a look over an architectural diagram of the same-

#In the top layer we have all the services like Azure… (wherein the user is created and present)
#In the bottom we have the apps(PHP, Xamarin) and the related data.
#Between the user and the data lies is the fence (i.e. Graph explorer) via which the user queries the data in the app.
#The user can only query the data after he has been authenticated and authorized and the auth protocol used here is OpenIdConnect

Via Graph Explorer we make the REST API calls and the response that we get is in JSON(Java Script Object Notation) format. (has a strange curly braces format)

Usability:

Well there must be some sense behind utilizing this mechanism of going via the fence(i.e. Graph Explorer) and accessing the data via the APIs(windows in the building)

Well, as stated earlier, the APIs have been exposed for a reason- so that the same can be leveraged to consume the data inside the building!
With respect to Intune, below are the use cases-

1- Portal Display Issues:

First lets talk about a scenario wherein a user clicks on Devices>Device Configuration and lets say that the portal does not load up and gives a 404 error/Page cannot be displayed error.

This is wherein the Graph Explorer comes in handy! Using the graph explorer tool we can access the same data which the portal was accessing and get the same information (which in this case would be a list of device configuration policies)

NOTE- Whenever we navigate through the portal by clicking on any blades, the portal at the back-end does a API call to the same database and then displays the output to is in a pretty format (instead of json format). We will see more of how this works later in this article.

2- Ease of Administration:

Now lets talk about a scenario wherein we need to create 100 Device Configuration policy, or publish/assign 100 apps.
Now it would be very difficult to do this manually from the portal. We would have to create each policy one at a time and fill in several fields which we wish to configure/not configure in each policy, name the policy, assign the policy etc..
The smoother way of making this work would be using Graph Explorer tool to create the policy by providing the policy body which would create 1 policy in each shot! Thus saving us a lot of time.

3- Automation:

And finally, the API calls can be made via Powershell which can automate the things for us.!
Just by the run of a .ps1 we can export the reports/create all 100+ needed policies and deploy all the apps as per requirement.!

Accessing the Graph Explorer and Permissions needed:

We can access the graph explorer from any browser by accessing the link- aka.ms/ge
Once we are at the website, below is what we see-

(Old interface):

(New Interface):

This is the landing page of the Graph Explorer tool and all the API calls that we make would be from here.
It Primarily has 3 sections-
1- Section to enter the API call(query)
2- Section to enter the Request Body (kind of Inputs to the API query, more on this later in the article)
3- Section which displays the output- the data returned by the service.
However, before we can start running queries on the tool there are a couple of steps we need to follow-

#We need to sign into the GE explorer using an Admin account(obviously an end users would/should not have the privileges to access the Intune service data)

#We have to authorize the logged in user to access the data via this tool.

Once done, we are now all set to get going with the tool!

USING GRAPH EXPLORER:

The SYNTAX:

As stated earlier, using the Graph Explorer we are making the REST API calls and the response we receive is in json format.
There is a definite syntax to make a REST API call which follows a Tree Hierarchy Structure.
Like for example if we wish to make a App Protection/Configuration policy from the portal or to access list of enrolled devices, the respective path to that would be-

Microsoft Intune>Client Apps>App Protection Policy.
Microsoft Intune>Client Apps>App Configuration Policy.
Microsoft Intune>Devices>All Devices.

So we see that the base node is the same while accessing any node/any policy which is “Microsoft Intune”

Now lets talk about the syntax, which looks like below-

This translates to:
https://graph.microsoft.com/version/resource/id/property

Now lets do a breakdown the above syntax:
1- graph.microsoft.com — This is the base URL of the Graph Explorer medium.
2- v1.0- this is the version number. We have 2 version available- v 1.0 and beta.v1.0 includes generally available APIs. Use the v1.0 version for all production apps
The only difference between the 2 is- all the APIs that we are able to query via “V1.0” are not subjected to change. However the APIs that we are able to query via “Beta” are subjected to change if the need be.

3- /devicemanagement- This is the base node for Microsoft Intune.
The Microsoft Intune blade in the portal translates to “devicemanagement” in the API call.(which is what the browser is also eventually making at the backend)
Just like in the portal for any Intune related action we have to got to the “Microsoft Intune” blade and then traverse inside of it, similarly while making a REST API call, we go to the base node “Device management”.
4- /deviceconfiguration- This is the sub-blade inside of Microsoft Intune blade.

The above used REST API call via the Graph explorer translates to the below action performed at the portal which would also make the same REST API call.

Kinds of Operations/Commands:

We can perform a variety of actions in the Intune portal. We can go to a blade and view the devices/apps/policies. We can create a new policy/edit an existing policy/delete an existing policy.
Similarly to perform these actions from the Graph Explorer we have to use a specific HTTP Verb which co-relates to the corresponding action we are trying to do.

#GET –>Equivalent to viewing the existing policies/settings in the portal.

#Post –>Equivalent to creating a new policy at the portal.

#Patch –> Equivalent to modifying/updating an existing policy from the portal.

#PUT- (rarely used) –> Equivalent of replacing a setting in policy with another, much like Patch

#DELETE –> Equivalent to deleting a policy from the portal.

The below screen shot illustrates how to use these commands

Query Parameters:

We can use a query parameter to include more or fewer properties than the default response. A query parameter is typically used to get a filtered response.
For example lets say, if i go to the portal and go to “Users” the portal displays all the users in the tenant along with all its attributes.

Similarly if we were to get the same info from graph explorer, the API query would be-
https://graph.microsoft.com/v1.0/users

Below are the respective output which shows the same data in different formats:

Now lets say that we dont want all the users in my tenant as my output but a filtered response. i.e. we only want the users whose display name starts with “S” Or only the username and the UPN of all the users and not all their attributes.

The corresponding Query used would be- (respectively)
https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName, ‘S’)
https://graph.microsoft.com/v1.0/users?$select=mail,userPrincipalName

So we can use query parameters as a filter to get the response that we want by posing conditions.

There are a variety of Query parameters which we can use such as- $filter, $format, $select,$search are few of the commonly used ones.
Full list of query parameter –

https://docs.microsoft.com/en-us/graph/query-parameters

Ways of Running a Graph REST API call:

There are 2 ways of running a Graph query:

#1-Without a request body:

Lets say we have to View the policy or Delete a policy. In that case, all we need to do is make the corresponding API call to achieve the task. No other input is needed.
#GET and DELETE http verbs donot require any request body.

#2-With a request body

However lets imagine a scenario wherein we wish to create a policy.
Obviously just pointing to the right location wont be sufficient. We would have to also mention the policy body (which would contain the name of the policy, the policy description, the policy setting determining what will and what will not be enabled by the same)
These all settings are mentioned in the Request Body.
As the name suggests, we are making a API call and along with that we are requesting to send some information which is needed for that API call to function.
The POST, PATCH, and PUT methods require a request body, usually specified in JSON format.

Creating a policy from the Graph Explorer Tool:

Lets now make use of the above approach and try to create a policy using Graph explorer. We will create a policy with below attributes-
#Policy Name- DemoGraphExplorer
#Policy Type- Device Configuration
#Policy Body- Passcode minimum length (11), Alphanumeric password.

So if we were to do it from the portal, the endpoint would have been-

Now lets just attempt to do it via Graph Explorer.We would need 2 inputs to achieve the same.

1- Policy Body

2- API endpoint

#POLICY BODY:

We can see that the Policy”id” field is blank- as the same would be generated automatically when the policy is created for us.

#API ENDPOINT:

Now as viewed from the console we can see that a policy as per the above applied settings have been created!

Editing an existing policy via Graph Explorer

Now lets just say we wish to edit the newly created policy.One obvious way of doing this is via the portal itself.However below is how we would do it, if we were to do it via the Graph Explorer tool

New Policy Name- DemoGraphExplorer1234

New password length- 5

We would have to get the policy id of the policy we wish to edit.

Deleting from the portal:

Now lets just say we wish to delete something may that me an app, policy or a device.We will try to accomplish the same by using Graph explorer-

We would run the below API call from the Graph Explorer. We need to specify the policyid/deviceid we wish to delete.

We can see that the device is now being deleted from the portal.

Getting the information from Browser: F12 trace

Whenever we are clicking on any blade, in the backgroud it is doing a API call and getting a json output and then displaying it in a prettier format.
Now as displayed in this article, one must be wondering how did i manage to get the Request body and how did i reach to the conclusion that the portal was also making the same API call which we we re manually doing via GE.

All the browsers have a developer tab which gives us a peek of whats happening under the hood and the developer tab is what we are going to use.
Its very important that we get familiarized with this, as by using the developer tab, we can find the API calls being made..

Lets say we go to Microsoft Intune>All Devices.
Below is what we see which displays the list of devices enrolled to our tenant.

But before we click on All Devices, we will press F12 in our keyboard which will open the Developer Tab as below-

Landing page of the developer tab in browser-

First we will clear the session which would remove the old and unwanted API calls from the display.

Now we will start the capture and then click on Microsoft Intune>All devices.

Below is what the portal displays-

If we check the flow in the developer tab now below is what we see-

As highlighted, we see that the portal reached out to- /devicemanagement/manageddevices with the method “Options”. This is wherein the portal is inquiring the Intune service, what are its options and what kind of operations it can perform.

In the Response Headers we see that the response from the service which enlists the options (Actions that can be performed) – DELETE, GET, MERGE,POST PATCH PUT.

Now we see that the portal made another API call where it does a GET.

If we click on the Body, we get more information-

We see all the device names returned by the Intune service to the browser in JSON format. This is what is displayed to the admin in a pretty format at the console.
By default not everything that the API call responds is displayed in the portal.

Logging of activities:

All the activities performed by an Admin in the Ibiza console is logged.
Similarly all the activities performed via Graph explorer is also logged and can be viewed at the portal.

Conclusion:

If we want to perform any activity at the Intune service, there are many ways of doing it.
Using the old fashioned Ibiza is just one way.!
As illustrated in this article, we can use Graph Explorer and achieve the same in a more customized format.

Irrespective of the method used the background remains the same, i.e. we have to eventually make the REST API call (either manually via explorer or make the console do it for us at the background.
I would highly suggest fiddling with GE and explore this as much as possible!

Reference:

https://docs.microsoft.com/en-us/graph/api/resources/intune-graph-overview?view=graph-rest-1.0

https://docs.microsoft.com/en-us/graph/api/intune-devices-manageddevice-list?view=graph-rest-1.0