Microsoft Graph and Invoke-RestMethod [PowerShell]

While the PowerShell Microsoft.Graph modules are great, Microsoft Graph is an API opening many different methods for reading and writing data, including via the PowerShell Invoke-RestMethod command.

But why use Invoke-RestMethod instead of one of the many Microsoft.Graph module commands? The main reason for me has been that not all the data exposed by the API especially the Beta version of the API can be accessed using the PowerShell Graph modules.

An example I have is, at the time of writing you can’t get the mailbox setting “userPurpose” for a user from the beta Microsoft Graph using the PowerShell Graph module.

In this post I will show you an alternative method to get the “userPurpose” attributes. But the same method can be used to get/put/patch any other data from the Graph API using the PowerShell Invoke-RestMethod command.

What’s is the userPurpose attribute?
Creating an AzureAD Application
Sample PowerShell Script to get a user’s “userPurpose” attribute from Microsoft Graph using Invoke-RestMethod
You may also like

What’s is the userPurpose attribute?

If you are not familiar with the /mailboxsettings/userpurpose attribute, it lets you distinguish an Azure AD account between being an actual user vs a shared mailbox user, based on the type of mailbox connected to the user account. This attribute is especially useful when running bulk jobs where I don’t need to return or set values for shared mailboxes.

Creating an AzureAD Application

Before we get into the PowerShell, we will need to create an Azure Active Directory application. This will be used to authenticate our script and it is also where we will define the permissions our script will have to Azure AD

Logon to your Azure admin portal (https://portal.azure.com/) with an account that has permissions to register applications.
Under Manage click App registrations
Click New registration
- Give your application an appropriate name
- Use the “Select a platform” drop to select “Web”
- Click Register
Click Manage => API permissions Here you can define what permission(s) your script will have, for example to read the properties of all AzureAD users you could add Microsoft Graph “User.Read.All”

Click Manage => Certificates & secrets => Client Secrets
Click “New client secret”
- Give your secret a description, I personally like to use the script name
- Select an appropriate expiry period
- Click Add
- Make sure to take a copy of the value, we will need this for our script, and it will not be viewable again after leaving the page

Getting the properties for the script

In addition to the value of the secret created in the previous section we will also need your Tenant ID and the Application ID of the of the application created in the previous section

$tenantID – Your Tenant ID

Found on Azure AD under Manage => Properties =>Tenant ID

$applicationID – Your Application ID

On the overview page or your created App registration “Application (client) ID”

Sample PowerShell Script to get a user’s “userPurpose” attribute from Microsoft Graph using Invoke-RestMethod

# Connecting to Azure Parameters
$tenantID = "<insert your tenant ID>"
$applicationID = "<insert your application ID>"
$clientKey = "<insert the value of you created secret>"

# Authenticate to Microsoft Grpah
 Write-Host "Authenticating to Microsoft Graph via REST method"

$url = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$resource = "https://graph.microsoft.com/" 
$restbody = @{
         grant_type    = 'client_credentials'
         client_id     = $applicationID 
         client_secret = $clientKey
         resource      = $resource
}
    
 # Get the return Auth Token
$token = Invoke-RestMethod -Method POST -Uri $url -Body $restbody
    
# Set the baseurl to MS Graph-API (BETA API)
$baseUrl = 'https://graph.microsoft.com/beta'
        
# Pack the token into a header for future API calls
$header = @{
          'Authorization' = "$($Token.token_type) $($Token.access_token)"
         'Content-type'  = "application/json"
}

# Define the UPN for the user we want to get userPurpose for
$userid = '[email protected]'

# Build the Base URL for the API call
$url = $baseUrl + '/users/' + $userid + '/mailboxsettings/userpurpose'
 
# Call the REST-API
$userPurpose = Invoke-RestMethod -Method GET -headers $header -Uri $url

write-host $userPurpose.value