Support Tip: Getting Started with Microsoft Graph API

Hello everyone, today we have another post from Intune Support Escalation Engineer Mihai Lucian Androne. In this post, Mihai walks us through the concepts of Microsoft Graph API, shares how to get the API set up, and as well as an example demonstrates how you can leverage existing code samples to build your app.

=====

Working with Microsoft Intune gives us the opportunity to dive into many technical areas, and depending on your background, configuring a SCEP profile or a Bitlocker policy can be easy whereas something else like Graph API might seem a bit intimidating.

My objective here is to walk through the basic concepts of Microsoft Graph API with the hopes that by the time you finish this support tip, you will have the confidence to start automating Intune yourself. We’ll go through setting up your environment, a demonstration of how a Graph API-based app works, as well as a conceptual example of an application that I built to migrate policies from one tenant to another using existing code samples freely available on Github.

A Quick Intro to Microsoft Graph

Microsoft Graph is a unified REST API, a comprehensive experience for integrating the data and intelligence exposed by Microsoft services. Using Microsoft Graph, you can build apps that can interact with the data from all your users and design new processes or workflows to integrate with your organization needs. It can drastically increase your user satisfaction, consolidate internal security and ease the work of your IT department in managing different workloads.

It is simple in that there is a single endpoint to access data across all resources and one OAuth access token for secure access based on granted permissions.

Whenever you are using any of the Graph APIs, you will need to start with the one endpoint, add the version (v1.0 or beta) for the API you are trying to call and then the resource you are looking for. Of course, if you want to be more specific, you can construct accurate calls by attaching other optional properties and/or query parameters.

NOTE The beta endpoint includes APIs that are currently in preview and are not yet generally available or supported, thus are subject to change and are not recommended for production.

All the APIs get used via common HTTP methods so you will be able to read, modify, create or delete data from our backend services.

That’s just a brief overview of Graph but you can read more in our documentation here: https://docs.microsoft.com/en-us/graph/overview.

Setting Up Your Environment
Now that we have a bit of a sense of what Microsoft Graph is about and how it can be used, I want to be sure we have our environment ready for some Graph calls. Most of you probably have an Azure Active Directory tenant and an Intune license already, however if you don’t that’s not a problem. You can get an EMS trial here which will provide a base from where you can start building your environment. Any call made against Microsoft Graph require an access token which can only be issued by Azure Active Directory, thus having a tenant is mandatory. Also, as we are going to focus on Intune Graph APIs, we would need some Intune data, thus we need an Intune license to be able to call these APIs.

Within the Azure Active Directory (Azure AD) tenant you can have multiple applications calling Graph APIs. Since we will acquire an access token to call Intune Graph APIs, first we register our application (it doesn’t need to be built yet) with Azure AD. I won’t go into details about registering the application, however, you can find the steps detailed here. Microsoft Graph exposes granular permissions that control the access that apps have to resources, like users, groups, and device management (with Intune). For your application to be able to access Intune data, depending on its purpose, some or all of these permissions needs to be granted.

NOTE Currently all Intune device management permissions are delegated. This means that the application will need to have a signed-in user.

TIP If you plan to use PowerShell to call Intune APIs, you won’t need to register your application with Azure Active Directory.

A Note on Graph Explorer
Before going into any details on creating your application, whenever you need to test any of the Graph APIs I recommend starting with Graph Explorer. Designed specifically to perform Graph API calls, it will help you better understand how to call specific Graph APIs and see what data/responses are returned. You can easily access it through its shortcut http://aka.ms/ge or by its full URL. Bookmark it – if you work a lot with Graph API it’s something you will be referencing often.

NOTE When running Graph Explorer for the first time, it will not have access to any Intune resources. You will need to grant permissions for this app by clicking “Modify permissions” on the left side under your username. It will ask you to re-authenticate to accept the new permissions, and some may also require Global Admin rights in the service.

Building Your App
Once your app is registered with Azure AD AAD, you are now ready to start building it. A high-level model of your application flow will look something like this:

NOTE By default, Microsoft Graph will return a maximum of 1,000 objects in one page when any of the APIs are called. If you expect more than 1,000 objects, you’ll want to implement paging. Here is our documentation around this topic. A PowerShell example can also be found here.

Following the above diagram, first we authenticate with Azure AD to get an access token for our application, then we start making our calls. At this point we have only registered the application in our tenant, however before we are able to authenticate using one of our Azure AD users there is still some coding left. This means adding ADAL or MSAL authentication libraries into your application. Depending on the platform you are using to develop your application, there might be some things you’ll want to consider. For tutorials and code samples around Microsoft Graph, please visit our get started page. From here you can download our Graph SDK and find already built applications and code snippets for each available platform. Use them as inspiration for your application design. You can also re-use the available code for faster application development next time.

NOTE Currently all Intune device management permissions are delegated so you will need to acquire an access token on behalf of a user.

If you are using PowerShell, we have some good news for you. My colleague David Falkus did a great job and created a GitHub repository for Intune PowerShell samples. This is the best place to start when you are looking for inspiration to code your application and here you will find examples covering most of the Intune features. For step 1 & 2 we got you covered: all scripts contain the authentication part where you would need to integrate the authentication libraries. You can copy this part to your script and benefit from it, just don't forget to copy the Get-AuthToken {…} function as well because authentication process relies on it.

Depending on the scenario you are trying to achieve, check the folders in GitHub samples. You might find a script already created. If your scenario is not already scripted by David, you will at least find one or more scripts that can fulfill some parts of your application and you can use that code to build your complete solution.

Building an Example
Now that we have all the pieces, the only thing left is to start gluing them together to build our app. I won’t go into the specific coding, however in the following section I present a conceptual example where I use Intune Graph APIs and some existing code samples to complete a full configuration policy migration from a pilot (testing) environment to production. If you’ve ever done this before manually then I’m sure you understand how much work can go into something like this. Using the power of Microsoft Graph API, we can automate the migration and transform it into something as quick as a five minute job.

The high-level architecture for my application looks like this:

There are three core steps for each environment, with the common one being the authentication part as we need to acquire an access token. The pilot environment will be the source for our configuration so we will pull the details about these policies and save them locally as JSON files. Then, once we have the data exported we create new policy entries in the production tenant based on that exported policy data. I won’t go into the specific coding details of my app, however to better visualize how I designed it, here is the code flow for the export (Pilot Env) and the import (Prod Env):

Highlighted in blue are the PowerShell functions that were used to design this application while with orange you will find some key parts for the application flow like Graph API endpoints or mandatory parameters. All highlighted functions exist within the PowerShell scripts from the GitHub repository I mentioned earlier except for List-JSONPolicy{…} which is not mandatory, however I created it to follow a nice pattern for the code flow.

If you take a look at the two scripts DeviceConfiguration_Export and DeviceConfiguration_Import from our GitHub repository, they represent the export and import portions of my application code. While designing this tool, I simply took big chunks of code from these scripts, put them together into one single app, and then extended the functions to work with multiple policies with for-each loops. This way I saved myself hours of coding by adjusting these scripts to fit my needs instead of creating something from scratch.

A Couple Tips
- If you are looking to export all of the configuration policies from your tenant, be aware that currently ADMX template policies are under the deviceManagement/groupPolicyConfiguration endpoint. This is a beta API only and it is subject to change so take this into consideration when developing your own app.
- If you have Scope Tags assigned to your policies in your pilot environment, this information will be exported as well along with the rest of the properties. This could potentially cause errors while importing the policies into the production tenant if those same Scope Tags don’t exist there. I would recommend excluding this property when you parse the JSON file that is going to be imported.

Extending the Application
With all the available Graph API calls there are endless possibilities for how you can integrate these into applications that will improve and streamline your business processes. The Pilot to Production migration tool in our example can be easily expanded for other types of policies and I invite you to try these scenarios as well by following same pattern that I presented above:

Conclusion
I hope you enjoyed this post and maybe learned a little bit about the basics of Microsoft Graph, how to set up your environment, and the requirements for building an application and where to find some great code samples. With these examples and considering all of the possibilities available, you should be well on your way to getting started developing your own apps that will make managing your Intune environment even easier.

More Information
Here are a few more resources that will help you get started and further develop your apps with Graph API:
• General guidance: https://developer.microsoft.com/en-us/graph
• Intune v1.0 APIs: https://docs.microsoft.com/en-us/graph/api/resources/intune-graph-overview?view=graph-rest-1.0
• Intune beta APIs: https://docs.microsoft.com/en-us/graph/api/resources/intune-graph-overview?view=graph-rest-beta
• Changelog: https://docs.microsoft.com/en-us/graph/changelog?view=graph-rest-1.0
• 30 days of Microsoft Graph blog: https://developer.microsoft.com/en-us/graph/blogs/announcing-30-days-of-microsoft-graph-blog-series/
• Previous Intune Graph API blog: https://techcommunity.microsoft.com/t5/Enterprise-Mobility-Security/Intune-APIs-in-Microsoft-Graph-8211-Now-generally-available/ba-p/250487

Mihai Lucian Androne
Intune Support Escalation Engineer