PowerShell

Using Invoke-MgGraphRequest to Update Microsoft 365 User

The Invoke-MgGraphRequest cmdlet is a powerful tool in PowerShell for sending custom requests directly to the Microsoft Graph API. While there are specialized cmdlets for common tasks like updating users (e.g. Update-MgUser), sometimes using Invoke-MgGraphRequest offers greater flexibility, especially when you need more control over API requests or perform tasks that are not covered by existing cmdlets.

This article focuses on how to use Invoke-MgGraphRequest specifically for updating user properties in Microsoft 365 through the Graph API. We will cover syntax, usage examples, common errors and solutions, and use cases where this cmdlet shines.

Cmdlet Syntax for Updating a User

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/$userId" -Body <JSON body> -ContentType "application/json"

Where:

-Method PATCH: Specifies the PATCH HTTP method to update a resource.
-Uri: This is the full Microsoft Graph API endpoint for the user (https://graph.microsoft.com/v1.0/users/{user-id}).
-Body: The JSON payload that contains the properties you want to update.
-ContentType "application/json": Specifies the content type of the request body.

Usage Examples

Example 1: Update User Display Name

# Define the user ID or UPN (User Principal Name)
$userId = "85fcdac1-5016-4bc3-b311-ad06fd410839"

# Define the update payload here, updating the display name
$body = @{
    displayName = "Sir Ian Botham"
} | ConvertTo-Json

# Perform the PATCH request to update the user's display name
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/$userId" -Body $body -ContentType "application/json"

This example updates the display name of the user identified by $userId to “Sir Ian Botham”.

Example 2: Update User Job Title and Department

$userId = "85fcdac1-5016-4bc3-b311-ad06fd410839"

$body = @{
    jobTitle = "Senior Manager"
    department = "IT"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/$userId" -Body $body -ContentType "application/json"

This updates the user’s job title to "Senior Manager" and department to "IT".

Example 3: Update User Mobile Phone Number

$userId = "85fcdac1-5016-4bc3-b311-ad06fd410839"

$body = @{
    mobilePhone = "+1 555 123 4567"
} | ConvertTo-Json

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/$userId" -Body $body -ContentType "application/json"

Cmdlet Tips

Ensure API Permissions: Before making updates, ensure your app or service principal has the necessary permissions (such as User.ReadWrite.All).
Validate Payload Format: The payload must be in valid JSON format. Use ConvertTo-Json to ensure proper formatting.
Use Complete URL: Always provide the full URL for the Graph API request (e.g. https://graph.microsoft.com/v1.0/users/{user-id}) to avoid errors.
Check API Limits: Be mindful of API throttling limits, especially if you're updating a large number of users.

Use Cases for Invoke-MgGraphRequest

Advanced Property Updates: While Update-MgUser can handle many user updates, Invoke-MgGraphRequest allows for more flexibility, especially when working with properties not easily handled by other cmdlets.
Automation of Bulk Updates: You can use this cmdlet to automate updates for multiple users by looping through a list of user IDs and making specific updates.
Handling Custom Scenarios: Sometimes administrators need to update user properties that are not directly supported in PowerShell cmdlets, such as custom attributes or other Graph API-specific fields. In such cases, Invoke-MgGraphRequest can be a lifesaver.

Possible Errors & Solutions

Error	Cause	Solution
Error: 401 Unauthorized	Lack of proper permissions	Ensure you have User.ReadWrite.All or Directory.ReadWrite.All permissions in Azure AD.
Error: 400 Bad Request	Invalid request body or URL	Check the payload JSON formatting and verify the URL is correct (e.g. use the full API URL).
Error: 404 Not Found	User ID is incorrect or user does not exist	Double-check the $userId variable to ensure it points to a valid user.
Error: Too Many Requests (429)	API throttling due to hitting rate limits	Implement retry logic with exponential backoff, especially when dealing with bulk updates.

Conclusion

While specialized PowerShell cmdlets like Update-MgUser offer convenience, Invoke-MgGraphRequest provides a flexible, powerful way to interact with the Microsoft Graph API for tasks that require customizations or access to advanced features. Whether you need to update a user's display name, department, or job title, Invoke-MgGraphRequest allows you to accomplish this with ease.

In cases where Graph PowerShell cmdlets fall short, this generic request cmdlet provides a way to perform any operation supported by the Graph API, making it an essential tool for administrators. By leveraging this flexibility, IT admins can address a variety of scenarios from bulk updates to custom user property management.