Using Invoke-MgGraphRequest to Remove Microsoft 365 Users

This guide explains how to use the Invoke-MgGraphRequest cmdlet in Microsoft Graph PowerShell to remove users from Microsoft 365. Learn how to construct API requests to delete single or multiple users with practical examples.

Invoke-MgGraphRequest cmdlet presents a flexible alternative for scenarios where you might need to directly interact with Microsoft Graph API endpoints. This article will guide you through using Invoke-MgGraphRequest to remove users from your Microsoft 365 tenant. We'll cover the cmdlet's syntax specific to user removal, usage examples, cmdlet tips, possible errors and solutions and some use cases.

Note: Remove-MgUser is the Graph PowerShell cmdlet equivalent for removing users.

Cmdlet Syntax

Invoke-MgGraphRequest -Method Delete -Uri "https://graph.microsoft.com/v1.0/users/{userId}"

• -Method Delete: Specifies the HTTP method to use, which in this case is DELETE to remove a user.
• -Uri: The URI endpoint for the Microsoft Graph API to remove a specific user by their userId.

Usage Examples

Example 1: Single User Removal

This example demonstrates how to remove a single user from your tenant using their User ID:

$userId = "user@domain.com"
Invoke-MgGraphRequest -Method Delete -Uri "https://graph.microsoft.com/v1.0/users/$userId"

Example 2: Multiple User Removal

You can remove multiple users by iterating through a list of User IDs:

$userIds = @("user1@domain.com", "user2@domain.com", "user3@domain.com")

foreach ($userId in $userIds) {
    Invoke-MgGraphRequest -Method Delete -Uri "https://graph.microsoft.com/v1.0/users/$userId"
}

Example 3: Remove Users by Reading Data from a CSV File

CSV File Structure:

UserId
user1@domain.com
user2@domain.com
user3@domain.com

This example shows how to remove users by reading their User IDs from a CSV file:

$csvPath = "C:\Path\To\Users.csv"
$users = Import-Csv -Path $csvPath

foreach ($user in $users) {
    Invoke-MgGraphRequest -Method Delete -Uri "https://graph.microsoft.com/v1.0/users/$($user.UserId)"
}

Cmdlet Tips

• URI Construction: Ensure that the URI is correctly formatted to avoid errors.
• Error Handling: Implement error handling in your scripts to manage scenarios where the user cannot be found or the request fails.
• Batching Requests: For large-scale operations, consider batching your DELETE requests to optimize performance.

Possible Errors & Solutions

Error: 404 Not Found

Cause: The specified user ID does not exist in the tenant.

Solution: Verify the User ID and ensure it exists before making the request.

Error: 403 Forbidden

Cause: Insufficient permissions to delete the user.

Solution: Ensure your account has the necessary M365 admin permissions (e.g., User Administrator or Global Administrator) and Graph API permissions (User.ReadWrite.All).

Error: 400 Bad Request

Cause: The URI or method is incorrectly formatted.

Solution: Double-check the URI and ensure that you are using the correct HTTP method (DELETE in this case).

Error: Invoke-MgGraphRequest : A parameter cannot be found that matches parameter name 'BodyParameter'.

Cause: -BodyParameter payload is not supported for Invoke-MgGraphRequest cmdlet.

Solution: Just use -Body instead of -BodyParameter and the cmdlet will work.

Use Cases

• Automated User Cleanup: Regularly remove inactive users from your tenant by scheduling a PowerShell script.
• Bulk User Deletion: Simplify the process of removing multiple users by automating it through a CSV file.
• Compliance & Security: Ensure that users who should no longer have access to your tenant are permanently removed.

Frequently Asked Questions

1. What is Invoke-MgGraphRequest used for?

Invoke-MgGraphRequest is a Microsoft Graph PowerShell cmdlet used to make custom API calls, including requests to delete users from Microsoft 365.

2. Can I confirm if a user was deleted successfully?

Verify by trying to retrieve the user using their UserPrincipalName. If the user does not exist, an error will occur:

Get-MgUser -UserId "<UserPrincipalName>"

3. What permissions are required to remove users?

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

Conclusion

The Invoke-MgGraphRequest cmdlet offers flexibility when performing actions not directly supported by specific cmdlets. By leveraging this cmdlet, you can efficiently manage user deletions in your Microsoft 365 tenant, whether removing single users, handling bulk deletions, or ensuring permanent removal from the tenant. Properly handling errors and constructing the correct URIs are crucial to the successful execution of these tasks.

By following the examples and tips provided in this article, you should be well-equipped to use Invoke-MgGraphRequest effectively for user removal operations.

Additional Resources:

Related Articles: