Using Invoke-MgGraphRequest to Fetch Microsoft 365 Users

The Invoke-MgGraphRequest cmdlet in the Microsoft Graph PowerShell module is a powerful and versatile tool that allows administrators to perform custom API calls to Microsoft Graph. While specific cmdlets like Get-MgUser exist to fetch Microsoft 365 user details, Invoke-MgGraphRequest provides greater flexibility for scenarios where precise control or advanced filtering is required.

Syntax for Fetching Users

Here is the syntax for using Invoke-MgGraphRequest to fetch Microsoft 365 users:

Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/users'

Usage Examples

Example 1: Fetch All Users

This example demonstrates how to fetch all users from the Microsoft 365 tenant and loop through the results to display specific details.

$response = Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/users'

if ($response.value) {
    foreach ($user in $response.value) {
        Write-Output "User Details:"
        Write-Output "Display Name: $($user.displayName)"
        Write-Output "Email: $($user.mail)"
        Write-Output "User Principal Name: $($user.userPrincipalName)"
        Write-Output "`n"
    }
} else {
    Write-Output "No users found or the response does not contain a 'value' property."
}
                            

Example 2: Fetch a Single User by User Principal Name

This example fetches details of a single user based on their User Principal Name (UPN):

$upn = "johndoe@contoso.com"
$response = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/users/$upn"

if ($response) {
    Write-Output "User Details:"
    Write-Output "Display Name: $($response.displayName)"
    Write-Output "Email: $($response.mail)"
    Write-Output "User Principal Name: $($response.userPrincipalName)"
} else {
    Write-Output "No user found with UPN $upn."
}
                            

Cmdlet Tips

• Filter and Select Specific Properties: You can append $select to the URI to fetch only specific properties, reducing response size and improving performance. Example:

  Invoke-MgGraphRequest -Method GET -Uri 'https://graph.microsoft.com/v1.0/users?$select=displayName,mail,userPrincipalName'

• Pagination: For large tenants, the results may be paginated. Use the @odata.nextLink property from the response to fetch the next set of results:

  $uri = 'https://graph.microsoft.com/v1.0/users'
  do {
      $response = Invoke-MgGraphRequest -Method GET -Uri $uri
      if ($response.value) {
          foreach ($user in $response.value) {
              Write-Output $user.displayName
          }
      }
      $uri = $response."@odata.nextLink"
  } while ($uri)

• Error Handling: Use try-catch blocks to handle potential errors effectively.

Possible Errors & Solutions

Connect-MgGraph -Scopes "User.Read.All"
                                            

Use Cases

1. Enhanced Customization: While Get-MgUser offers built-in functionality for fetching users, Invoke-MgGraphRequest allows administrators to:
• Fetch only specific properties.
• Perform complex filtering and searching not supported by default cmdlets.
2. Advanced Reporting: The ability to include or exclude specific fields makes this cmdlet ideal for creating detailed, tailored reports.
3. Integration with External Systems: By customizing API calls, administrators can integrate user data into third-party applications or workflows.

Conclusion

The Invoke-MgGraphRequest cmdlet is a robust and flexible tool that complements standard Graph PowerShell cmdlets. By allowing custom API requests, it supports advanced automation and integration scenarios, making it indispensable for Microsoft 365 administrators. While it requires more effort compared to purpose-built cmdlets, its flexibility makes it a valuable addition to your administrative toolkit.