Working With the Microsoft Graph API

Recently, I was asked to collect data about our Microsoft licenses and users in our Azure Active Directory who are consuming those licenses. This presented the perfect opportunity to work with the Microsoft Graph API!

Microsoft Graph is a RESTful API that allows you to access Microsoft Cloud services resources. It supports GET, POST, PATCH, PUT, and DELETE requests. To make a request to the API, you need to:

  1. Register an app in Azure
  2. Request an authentication token using the app registration credentials
  3. Make a request by passing that token in the header to a Graph endpoint

See the Microsoft documentation for more information on the Microsoft Graph API.

Let’s walk through this and see how we can use the Graph API to get details about our Microsoft licenses.

Creating an app registration straight forward. You will need to ensure your app registration has a client secret and the delegated User.Read Microsoft Graph API permission. I would recommend following the Microsoft quick start guide on registering an application with the Microsoft identity platform.

Remember to not lose your client secret! It is a good idea to add your client secret to a key vault to store it securely within your Azure environment.

Once you have an app registration with a client secret and the proper API permissions, you should be able to make requests against the Microsoft Graph API. A great way to test this is using Postman.

As usual, Microsoft has some solid documentation on using Postman with the Microsoft Graph API that you should check out if you are new to it.

The first step is to make a POST request to get the bearer token that will be used in the header of the request for the list of licenses and user assigned licenses. To do this, we will use the OAuth 2.0 Client Credentials Grant flow.

To get our token, we will submit a POST request to:

https://login.microsoftonline.com/<your-tenant-id>/oauth2/token

With the following body content:

  • grant_type – this should be equal to “client_credentials
  • client_id – the ID of the app registration you created earlier
  • client_secret – the client secret you generated when creating your app
  • resource – this should be equal to “https://graph.microsoft.com

Submitting this request should return some basic details about the token such as its type, expiration, the targeted resource, and most importantly the bearer or access token.

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1619793287",
    "not_before": "1619789387",
    "resource": "https://graph.microsoft.com",
    "access_token": "************************"
}

Now we can create our request for the list of available licenses (subscribed skus) in our tenant!

To do this, submit a GET request to:

https://graph.microsoft.com/v1.0/subscribedSkus

With the following headers:

  • Authorization – this should be equal to “Bearer <your-bearer-token>

Submitting this request will return something like the following:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscribedSkus",
    "value": [
        {
            "capabilityStatus": "Enabled",
            "consumedUnits": 4,
            "id": "********",
            "skuId": "1f2f344a-700d-42c9-9427-5cea1d5d7ba6",
            "skuPartNumber": "STREAM",
            "appliesTo": "User",
            "prepaidUnits": {
                "enabled": 1000000,
                "suspended": 0,
                "warning": 0
            },
            "servicePlans": [
                {
                    "servicePlanId": "113feb6c-3fe4-4440-bddc-54d774bf0318",
                    "servicePlanName": "EXCHANGE_S_FOUNDATION",
                    "provisioningStatus": "Success",
                    "appliesTo": "Company"
                },
                {
                    "servicePlanId": "********",
                    "servicePlanName": "Microsoft Stream",
                    "provisioningStatus": "Success",
                    "appliesTo": "User"
                }
            ]
        }
    ]
}

You can use the same bearer token in the header to make other requests to the Microsoft Graph API as well. If you wanted to get a list of all users who have access to a particular license SKU (in this case the Microsoft Stream SKU) you could:

Submit a GET request to:

https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq 1f2f344a-700d-42c9-9427-5cea1d5d7ba6)

Submitting this request will result in something like this:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
    "value": [
        {
            "id": "*****",
            "mail": "*****@yourorg.com",
            "assignedLicenses": [
                {
                    "disabledPlans": [],
                    "skuId": "f8a1db68-be16-40ed-86d5-cb42ce701560"
                },
                {
                    "disabledPlans": [],
                    "skuId": "1f2f344a-700d-42c9-9427-5cea1d5d7ba6"
                }
            ]
        },
        ... truncated ...
    ]
}

The filter option in the request is an example of a query parameter supported by the Graph API. Query parameters allow you to control how much data comes back in the response.

See the Microsoft documentation for more information on query parameters.

I have only scratched the surface on the endpoints available for the Microsoft Graph API. It is very powerful and will quickly become a normal part of the way you work as a Cloud developer. For a complete reference to the 1.0 documentation, click here.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: