An introduction into the Graph API

Whenever you are managing a Microsoft 365 environment, you regularly come across repetitive tasks:

• Creating new Intune policies
• Setting up users
• Retrieving security data
• …

For all these tasks, Microsoft 365 has the ability for some automation. During this blog post, I will walk you through how to get started with the Graph API and provide you with some tips and tricks. This blog is meant for users who are just starting out with the Graph API.

Introduction

All of the automation capabilities that I am going to cover are about the Microsoft Graph API. The Microsoft Graph API is the general endpoint for almost all Microsoft products. It uses a uniform method of authentication/querying across all the different endpoints, which makes it really convenient to switch between platforms.

To get started with the Graph API there are a few important things to get of the way first:

Endpoints

The Graph API has two main endpoints:

• v1.0
• beta

The v1.0 endpoint is the stable, public release version which is meant for production use. The beta version is where all the new stuff is at though. This contains all the latest and greatest, but is bound to change and isn’t recommended for production use.

You should always aim to use the v1.0 endpoint for production use, but you will soon notice that not everything is available here. Most new (1-6 months old) Intune features are only available in the beta endpoint.

App registrations

Authentication for the Graph API is handled entirely by Azure AD. The technical explanation on how authentication with service principals works is for another blog, for more information check out the Microsoft docs.

There are two important things you need to know about app registrations

• How you can assign the correct permissions
• How you can authenticate to it

Permissions

When you create a new app registration, you will notice that there are two types of permissions:

• Delegated permissions
• Application permissions

Like the AAD portal shows, there is a clear distinction between the two.
If you are creating an application where a user is actively logging in and you want to access that users data, then you need delegated permissions.
Are you writing an application or script that runs in the background (as a service or an Azure Automation Runbook), use application permissions .

So for scripts and any backend tasks, application permissions are the way to go. Note that application permissions are not available everywhere throughout the Graph API. Some endpoints, such as PIM and Planner don’t support application permissions across the board. In a case like this, you have to use delegated permissions. It’s far from ideal, but sometimes it’s the only way to go.
In this case, you would have to create a service account and exclude it from your MFA policy. In order to secure the account, it is best to limit the places where a user can log in from (through Conditional Access for example).

Admin consent

Whenever you have assigned permissions to an app, the user who is logging in needs to provide ‘consent’. This means the user acknowledges the permissions an app will have over the data (comparable when you give an app access to your camera on your mobile phone).

An administrator has the option to provide ‘admin consent’, this means that consent will be provided for every user in the tenant. This needs to be executed by a Global or Application Administrator. Whenever you are using application permissions, you will need admin consent.

Authentication

There are a lot of different ways to authenticate to the Graph API. How you authenticate also varies if you are using application or delegated permissions. When you are delegated permissions, somebody will be logging in through username and password. With application permissions, you will be logging in through a certificate or application secret.

The Lazy Administrator has written a good blog on authenticating with delegated permissions.

For application permissions, check out this Microsoft blog. It is important to store the certificate/secret securely as an attacker can use this to get access to your environment. Whether you use a certificate or secret is up to you. Microsoft recommends using certificates as certificate are typically better secured.

Getting the right Graph Request

After you have authenticated, it’s time to build your first request. When you are first starting out, it can be pretty difficult to know what your exact request show be.
For example, if you want to retrieve an Intune device ‘https://graph.microsoft.com/v1.0/devicemanagement/devices’ isn’t correct. The correct syntax here is ‘https://graph.microsoft.com/v1.0/devicemanagement/managedDevices’

The best way to find out the right queries, it to use the Graph docs. These docs allow you the choose the right Graph endpoint (v1.0 or beta) and enable you to search for the right query.
As mentioned before, it’s better to use the v1.0 endpoint whenever possible.

oData parameters

The Graph API has a bunch of different parameters available called ‘oData parameters’, these are based on the oData query language.
These parameters enable you to filter on certain properties or change the properties that the query returns and much more!

Tips and tricks

Before concluding this blog, I would like to end things with a few tips and tricks.

Graph Explorer

The Graph Explorer is a website which lets you easily test out queries without having to write your own script. It’s available through the url aka.ms/ge

It has a bunch of functionality:

1. You can use some sample data from Microsoft, or login with your own AAD account and use your own tenants data
2. There are a few simple queries available if you are just getting started
3. You can easily write queries and test the outputs directly from your browser

Powershell modules

If you are not comfortable writing your own Graph queries, there a Powershell modules available as a replacement (albeit with limited possibilities).

• Microsoft Graph Module
• Microsoft Graph Intune Module

30 days of Graph

When I first started out with Graph, the ’30 days of Graph’ series helped me out a lot. This was a lot series from 2018 which went over a lot of the core functionality of the API. If you are just starting out, I highly recommend checking this out.