Invoke-MgGraphRequest: Update Microsoft 365 Users Using Graph PowerShell

This guide demonstrates how to use the Invoke-MgGraphRequest cmdlet in Microsoft Graph PowerShell to update user details in Microsoft 365. Learn how to modify properties like job title, department, and mobile phone number with practical examples.

Updating a user in Microsoft 365 using Graph PowerShell often involves specific cmdlets like Update-MgUser. However, there are scenarios where you may need to use a more flexible approach, such as Invoke-MgGraphRequest, which allows you to send custom Graph API calls directly. This article will guide you through using Invoke-MgGraphRequest to update a user, offering practical examples, tips, common errors, and real-world use cases.

Why Use Invoke-MgGraphRequest for User Updates?

• Custom API Requests: If you need to make updates not covered by Graph PowerShell cmdlets, you can use the full range of Graph API capabilities with this cmdlet.
• Efficiency: You can update multiple users in bulk with custom configurations, especially useful when working with specific or lesser-known properties.
• Flexibility: Allows more control over the API calls, enabling admins to tweak requests to meet unique requirements.

Cmdlet Syntax

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/users/{id}" -Body @{
    passwordProfile = @{
        forceChangePasswordNextSignIn = $true
        password = "NewPassword123"
    }
}

The key parameters are:

• -Method: The HTTP method, in this case PATCH for updating.
• -Uri: The full API URL for the user (e.g., https://graph.microsoft.com/v1.0/users/{id}).
• -Body: The payload that defines the update, formatted as a hashtable.

Usage Examples

Example 1: Single User Update

$uri = "https://graph.microsoft.com/v1.0/users/sam.user@contoso.com"
$body = @{
    passwordProfile = @{
        forceChangePasswordNextSignIn = $false
        password = "SecurePassw0rd!"
    }
}
Invoke-MgGraphRequest -Method PATCH -Uri $uri -Body $body

In this example, the user sam.user@contoso.com will have their password updated to SecurePassw0rd! and won’t be required to change their password at the next sign-in.

Example 2: Updating Multiple Users' Work Location

$users = @("user1@contoso.com", "user2@contoso.com", "user3@contoso.com")
foreach ($user in $users) {
    $uri = "https://graph.microsoft.com/v1.0/users/$user"
    $body = @{
        officeLocation = "New York Office"
    }
    Invoke-MgGraphRequest -Method PATCH -Uri $uri -Body $body
}

This script updates the officeLocation attribute for each user in the list to "New York Office".

Example 3: Bulk Update User Properties from CSV

$users = Import-Csv -Path "C:\Users.csv"
foreach ($user in $users) {
    $uri = "https://graph.microsoft.com/v1.0/users/$($user.UserPrincipalName)"
    $body = @{
        displayName = $user.DisplayName
        jobTitle = $user.JobTitle
        department = $user.Department
        mobilePhone = $user.MobilePhone
    }
    Invoke-MgGraphRequest -Method PATCH -Uri $uri -Body $body
}

This example uses a CSV file to update multiple user properties (DisplayName, JobTitle, Department, and MobilePhone) in bulk.

Cmdlet Tips

• Use Full API URLs: Always use the full API URL when making requests with Invoke-MgGraphRequest (e.g., https://graph.microsoft.com/v1.0/users/{id}).
• Test in Batches: If performing bulk updates, test your script on a small subset of users to ensure it works as expected before scaling up.
• Error Handling: Use try-catch blocks in PowerShell to handle errors during the request process, especially for large batches of updates.
• API Permissions: Ensure you have the required permissions (such as User.ReadWrite.All) to update users via Microsoft Graph API.

Possible Errors & Solutions

Error	Cause	Solution
400 Bad Request	The request body contains invalid or incorrect values.	Double-check the properties and format of your body parameters. Ensure that you're sending the correct data type (e.g., Boolean for forceChangePasswordNextSignIn).
403 Forbidden	Insufficient permissions to perform the operation.	Ensure that the account running the script has the necessary Graph API permissions. You may need to request admin consent for User.ReadWrite.All.
404 Not Found	The user could not be found based on the provided ID or UPN.	Verify the UserPrincipalName or ID used in the API URL. Ensure that the user exists and that you have access to manage their details.

Use Cases

• Password Management: An IT administrator can use Invoke-MgGraphRequest to reset the passwords for a large set of users across multiple departments. This can be useful in security breaches where resetting credentials quickly is a priority.
• Automating User Profile Updates: Instead of manually updating user details like displayName or jobTitle, you can script the process using Invoke-MgGraphRequest, saving time and ensuring consistency across the organization.
• Bulk Account Adjustments: During a company reorganization, IT teams can use the cmdlet to update various user properties based on new reporting structures, pulling the required data from CSV files.

Frequently Asked Questions

1. What is Invoke-MgGraphRequest used for?

Invoke-MgGraphRequest is a Microsoft Graph PowerShell cmdlet used to make custom API calls, allowing updates to user properties in Microsoft 365 beyond the standard cmdlets.

2. How can I verify that a user's details were updated?

Use the Get-MgUser cmdlet to confirm the changes:

Get-MgUser -UserId "<UserPrincipalName>" | Select-Object DisplayName, JobTitle, Department

3. What permissions are required to update user properties?

You need the User.ReadWrite.All or Directory.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

Conclusion

While Microsoft Graph PowerShell offers specific cmdlets for most user-related tasks, Invoke-MgGraphRequest is a powerful and flexible alternative when you need to perform custom operations or when cmdlets fall short. By leveraging direct API calls, you can automate updates for single users, multiple users, or even bulk changes via CSV, significantly streamlining your administrative workflows. Ensure that you use proper error handling and testing, and don’t forget to verify your API permissions to avoid common issues.