Get Started with Graph API for Entra and Intune

A few weeks back I presented at BrainStorm K20 Wisconsin Dells where my key session was related to getting started with the Microsoft Graph API. The session went very well, and I have received a significant amount of positive feedback including some "best of the conference" feedback notes. I appreciate those kind words, but at heart it indicates that collectively we need to do more community-based engagement to get folks familiar with Graph API and help demystify the practical bits.

So a quick-ish primer it is; hopefully folks can find something useful and insightful from this post for their own starting point(s)!

What Is This "Graph API" Thing?

If you browse around, you'll see folks toss out references to Graph and Graph API like candy at a parade. Graph and Graph API can actually mean many things; since I primarily work in the device management space, I generally use Graph in two areas: Microsoft Entra, and Microsoft Intune. Graph API is the way to interact with these services via code (or mechanically), and interestingly enough is actually a large part of what's being used under the hood to power the Entra and Intune portals we all use in our environments.

Graph API is a REST API that's available for a ton of Microsoft 365 services. As such, it works like many other REST APIs: you have some "credentials," request a token/authenticate, and make GET/POST/PUT/PATCH/DELETE HTTP requests with or without parameters or payloads to Do Things. When I do this sort of session at a conference, I often spend a bit of time discussing the nuances and basics of REST depending on the audience and their backgrounds.

Accessing Graph API

Ignoring the actual mechanism of authentication, there are essentially two types of permissions with Graph API:

1. Delegated — akin to invoking actions as a user or principal; and
2. Application — akin to invoking actions as a service or headless/ephemeral process.

In Graph, some actions are restricted to types of permissions. so you may be able to run an action with delegated permissions but not with application permissions (or vice versa). This can be an entire rabbit hole of its own, but the documentation generally indicates what type of permission(s) are necessary.

Permissions are important to understand as something using Delegated permissions will require the invoking user to authorize this action on their behalf (e.g. log in/authenticate the first time). Application permissions, on the other hand, are generally pre-authorized in the sense credentials are already generated and therefore can be run without any user interaction.

Regardless of permission type, when configuring access during the setup process you'll need to assign the proper access roles and scopes for user, otherwise requests will fail. This is especially important to understand with Delegated permissions: an actual user involved with the request might normally have access do something in the portal, but permissions also need to be assigned in configuration of the API project as well. I end up using Application permissions more than Delegated since most of my real stuff runs headless/as a service. One example from my lab environment looks like this:

Creating an API "Project"

There are three things you need to do (two at minimum) to get started actually using the Graph API:

1. Configure an App Registration

   1. Ideally you create an app registration for each "thing" and not reuse across use cases/situations.

      

2. Configure API Permissions
   1. This is where you set up scopes for access, determine if your project is using Delegated or Application permissions, address scope approvals (if necessary) on behalf of the organization, and so forth.
   2. Pro Security Tip: Read the permissions reference documentation and/or use Merill's Graph Permissions Explorer to fine-tune your API scopes versus using the "easy" options for more broad read/all access.
3. Set up Certificates and Secrets

   1. These are required for Application-based permissions and are the keys used to obtain the real-time access tokens for requests.

      

In the above screenshots, I'm showing details for an example app registration I use for demos and illustration. Certificates are awesome to use if you're able, but for getting started it's usually simpler to start with client secrets. Something important to note is that you will only see the "Value" for a new client secret initially and there's no way to see the full value later (as illustrated in the above screenshot). 

Great, Let's Actually DO Something!

Now we've gone over the essentials of setting up a project and the considerations for access, we can talk about actually doing something with Graph API. And that means "talking" to it. There are a few mechanisms to do this, including:

• Use an Official SDK
  • Benefits: Available for many common languages, including Powershell, Python, etc.
  • Disadvantages: Can be overwhelming to get started since you're thrown into the deep end.
• Use direct HTTP requests
  • Benefits: Clean, concise, easily portable, and explicit (no abstraction)
  • Disadvantages: Nothing to handle pagination, tokens, etc. - you have to do it all
• Graph Tutorials/Graph Explorer
  • Benefits: Step-by-step guides to get started, includes code snippets with Graph Explorer
  • Disadvantages: Limitations in examples and use cases for anything beyond a starting point

Tools Exist To Assist!

There are several tools and utilities that can help in this process, though. These include:

• Postman

  • Microsoft has a "forkable" set of Graph API examples, which is super useful for starting with direct HTTP requests

    

• Graph X-Ray

  • This browser extension exposes Graph requests in real-time as they are invoked. You use the extension while browsing the portals and it will illustrate the direct HTTP requests and/or Graph Powershell cmdlets that were used or could be used to obtain or source the data on screen -- what's AWESOME about this is you can see exactly how the Entra/Intune (and other) portals use Graph under the hood to do what they do!

    

• Pro Tip: Get familiar with query parameters to help you craft more specific requests with less payload overhead!

Combining these tools is a great way to work through using Graph to Do Things. For example, I will browse around the portals with Graph X-Ray enabled to get pointers to the underlying REST calls, and then paste those into Postman to fiddle further (usually with query parameters, etc.). But even just having X-Ray's pointer at the proper module cmdlet is a major help when developing something of your own!

That's The 1,000 Foot View

Graph can be a beast, and this post barely touches the surface. But hopefully it helps to demystify some of the core concepts around using Graph. Fortunately, Microsoft's documentation is quite thorough, so along with the larger community it's often possible to figure this all out, but as noted it can be super overwhelming at first. Don't be deterred — it's not just you.

In the next scheduled post, I will illustrate a simple Powershell module I created to help demystify the direct HTTP method with Invoke-RestMethod in Powershell. This is intended to help folks try Graph API without getting bogged down with the other parts (like the full SDKs), but not necessarily to be used in a fully-fledged scenario. Until then, hopefully these pointers can get you in the neighborhood of using Graph API for fiddling with Entra and Intune! Good luck!