Report license usage rights with Microsoft Graph PowerShell

The Cloud licensing APIs, part of the Microsoft Cloud Licensing platform, help to improve licensing management and eligibility by breaking down licenses assigned to users by various subscriptions into smaller, more manageable pools called allotments. 

For example, you may need to determine if a user is eligible to use a specific feature of Microsoft 365. However, this is difficult as they may have many different licenses assigned, and you do not know which license holds this particular feature. For this, you can use the cloud licensing APIs to query the eligible features for a user to determine whether they are eligible or not.

In this article, I will show you how to use the cloud licensing APIs with Microsoft Graph PowerShell to report user license usage rights in Microsoft 365.

Requirements

Below are the requirements for using the Cloud license usage APIs with Microsoft Graph PowerShell.

To read license usage rights for any user in your organisation, the User-UsageRight.Read.All permission is required in either the Delegated or Application context.

To use the examples in this article you will need the Microsoft.Graph.Authentication PowerShell module installed. For help, see How To Install the Microsoft Graph PowerShell Module.

View license usage rights for a user

The Cloud license usage report APIs only work with the unique ID of a user and not the friendly UserPrincipalName. This means that you will first need to make a request to Microsoft Graph to obtain the ID of your target user.

 $userid = (Get-MgUser -Userid [email protected] -Property Id).Id

Once the ID is obtained, you can build a GET request to obtain the usage right information. You can see from the below that I am using the Invoke-MgGraphRequest cmdlet, this is because there are no dedicated cmdlets for this API currently. Use the below example to obtain the license usage rights for your target user.

 $UsageRights = Invoke-MgGraphRequest `
 -Uri "/beta/users/$userid/cloudLicensing/usageRights" `
 -Method GET `
 -OutputType PSObject | Select -Expand Value

Usage right information can then be displayed directly in your PowerShell console by using the following command.

$usageRights.services

Your output should look something like this:

Cloud license usage rights API example
Cloud license usage rights API example

Filter license usage rights by SKU

To filter a user’s license usage rights based on the license (or SKU) assigned to them, use the following example and modify the skuId in the first line.

$filter = "skuId eq c42b9cae-ea4f-4ab7-9717-81576235ccac"

$UsageRights = Invoke-MgGraphRequest `
-Uri "/beta/users/$userid/cloudLicensing/usageRights?`$filter=$filter" `
-Method GET `
-OutputType PSObject | Select -Expand Value

You can also filter by a collection of licenses by using the In operator, like so.

$filter = "skuId in (c42b9cae-ea4f-4ab7-9717-81576235ccac, a403ebcc-fae0-4ca2-8c8c-7a907fd6c235"

Filter license usage rights by Service Plan

To filter a user’s license usage rights based on the service plan within a license, use the following example and change the planId in the first line.

$filter = "services/any(c:c/planId eq 9c0dab89-a30c-4117-86e7-97bda240acd2"

$UsageRights = Invoke-MgGraphRequest `
-Uri "/beta/users/$userid/cloudLicensing/usageRights?`$filter=$filter" `
-Method GET `
-OutputType PSObject | Select -Expand Value

You can also filter by a collection of service plans by using the In operator, like so.

$filter = "services/any(c:c/planId in (9c0dab89-a30c-4117-86e7-97bda240acd2, 2049e525-b859-401b-b2a0-e0a31c4b1fe4))"

Licensing usage rights vs Get-MgUserLicenseDetail

Both the Cloud license usage rights API (at the time of writing this article) and the Get-MgUserLicenseDetails cmdlets can be used to solve the same or similar problems. Both APIs will retrieve the licenses assigned to a user, and include the service plans within their licenses.

When breaking down the responses, the data from both endpoints is the same, with a slight change in property names, which could indicate data is pulled from one, into the other without conflict on the back end.

Cloud licensing API cs GetMgUserLicenseDetail

A notable difference is in the information contained within the Service Plans. The below image highlights the response from the Cloud license usage rights API. As you can see, the service plans column highlights the type of object the service plan is assignable to, this cloud be a user, group or device according to the documentation.

Cloud licensing API service plans

Alternatively, the response from the Get-MgUserLicenseDetail cmdlet highlights whether the service plan is assigned through user or group-based licensing and also whether the service plan has been successfully provisioned for the user. This could be useful when the service takes a short while to provision after the license is assigned to the user.

GetMgUserLicenseDetail service plans

Also, as highlighted above, I demonstrated how you can use filtering with the Cloud license usage rights API. This is the core difference between the options. The Get-MgUserLicenseDetail endpoint does not support filtering, whereas the Cloud license usage rights API does. This could indicate that this data was copied to a separate data store to enable support for filtering specifically.

You should use these differences in data and capabilities to decide which is the more appropriate endpoint to use when obtaining licensing formation for a user.

Daniel Bradley

Daniel Bradley is a UK-based technical architect and Microsoft MVP in Security. He specialises in Microsoft Entra, Intune, and Microsoft Graph PowerShell and is the author of Microsoft Graph PowerShell for Administrators. He writes and edits Our Cloud Network using experience gained from working with Microsoft cloud environments.

Leave a Reply