Microsoft Graph (MS Graph) provides a REST API that allows you to access and manage many Active Directory (AD) objects, including information about users and their organizations. Microsoft Graph provides an API that allows you to read and write objects in Azure and Microsoft 365 objects. Examples include accessing and maintaining information on users, calendars, Teams, and devices.
You can call the Graph API by sending a POST, PUT, or GET request to a set of endpoints at https://graph.microsoft.com. As of this writing, MS Graph is on version 1.0, so all the endpoints begin with https://graph.microsoft.com/v1.0/, but that version number at the end may change in the future. These endpoints are documented here.
Some of these requests require sending some data in the HTTP body and all of them require sending data in the HTTP header. One common method of authentication is to send a Bearer Token in the header of each HTTP request. A JSON Web Token (JWT) is a type of Bearer Token issued by an identity provider, such as Azure Active Directory (AAD). It verifies the identity of the person or service making the API call, and it can contain information about that identity. In order to successfully, generate a JWT, you must create a user account; register an application with Azure Active Directory; and must generate a Client Secret; and you must grant the appropriate Microsoft Graph permissions to the account.
An API call runs as an account identity. That identity must be authenticated by someone that MS Graph trusts. That identity must have permission to perform actions in the API call
Another requirement of making a call to the Microsoft Graph API is that the caller must have permission to perform the requested actions on the objects specified in the request. For example, in order to read information about a user, the account must have READ permissions on the User object.
Fig. 1 illustrates the prerequisites to making a Graph API call.
Below are the steps (including prerequisites) when making a call to MS Graph. For each prerequisite, I have linked to an article describing the step in detail.
- Register App. Record Tenant ID and Client ID
- Create Client Secret
- Obtain appropriate AD permissions
- Create Token
- Call API
Once you have a token representing a user account and that account has the appropriate permissions, you can make a call to the Microsoft Graph API.
Let's start with a call to get all users. Send an HTTP GET request to https://graph.microsoft.com/v1.0/users.
Add the following key-value pair to the HTTP Header of the request:
where jwt is the JSON Web Token you created for the user account.
This is shown in Fig. 2.
As you can see, if we pass a valid JWT, the API returns a list of users in JSON format.
In this article, I introduced Identity Management and the Microsoft Graph API; I showed how they work together, and I provided step-by-step instructions on implementing IAM to access the API.