Using Invoke-MgGraphRequest to Fetch Microsoft 365 Users

Microsoft Graph PowerShell provides powerful cmdlets to manage Microsoft 365 environments. While many tasks can be performed using dedicated cmdlets, some advanced scenarios require direct API calls. The Invoke-MgGraphRequest cmdlet is your gateway to execute custom queries against Microsoft Graph. In this article, we’ll focus on using Invoke-MgGraphRequest to fetch user data, covering everything from basic examples to advanced usage tips.

Usage Examples

Example 1: Fetching All Users

The following script retrieves all users in the Microsoft 365 tenant and displays key details such as display name, email, and user principal name:

$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: Fetching a Single User by ID

To retrieve details of a specific user, replace user-id with the desired user’s ID (GUID or User Principal Name):

$userId = "user-id"  # Replace with the desired user ID
$response = Invoke-MgGraphRequest -Method GET -Uri "https://graph.microsoft.com/v1.0/users/$userId"

Write-Output "Display Name: $($response.displayName)"
Write-Output "Email: $($response.mail)"
Write-Output "User Principal Name: $($response.userPrincipalName)"
Write-Output "Account Enabled: $($response.accountEnabled)"
Write-Output "Job Title: $($response.jobTitle)"
                            

Cmdlet Tips

• Optimize Permissions: Grant your application the least privileged permissions required. For fetching user data, User.Read.All is sufficient.
• Pagination Handling: The Graph API may return large datasets in pages. Check for the @odata.nextLink property in the response and use it to fetch subsequent pages.
• Response Validation: Always validate the response structure. For instance, ensure the value property exists when fetching multiple users.
• API Versioning: The URI in your request (v1.0 or beta) determines the API version. Use beta for experimental features, but prefer v1.0 for production scripts.

Possible Errors and Solutions

Error Message	Cause	Solution
Access Denied	Insufficient API permissions	Ensure the app has User.Read.All or User.ReadBasic.All permissions.
404 Not Found	Invalid user ID	Verify the user ID and ensure the user exists in the tenant.
Invalid URI	Malformed URI in the API request	Double-check the API endpoint syntax.
ThrottlingError	Too many requests in a short time	Implement retry logic with exponential backoff.
Unauthorized	Invalid or expired access token	Reauthenticate and obtain a valid access token.

Use Cases

• Directory Reporting: Generate user reports with detailed information such as job titles, email addresses, and status.
• User Validation: Verify if a specific user exists before performing other administrative tasks.
• Data Integration: Integrate Microsoft 365 user data with third-party systems or custom dashboards.
• Compliance Audits: Fetch and review user account details to ensure compliance with organizational policies.

Frequently Asked Questions

1. Can I filter the data returned by Invoke-MgGraphRequest? Yes, you can use OData query parameters like $filter, $select, and $top in the API request URI. For example:

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

2. How do I handle paginated responses? Check for the @odata.nextLink property in the response. If present, repeat the request using its value:

   
   while ($response.'@odata.nextLink') {
       $response = Invoke-MgGraphRequest -Method GET -Uri $response.'@odata.nextLink'
       # Process the data
   }
                                       

3. Can I use this cmdlet with delegated permissions? Yes, ensure the user running the script has sufficient permissions (like User.Read or User.Read.All) and is authenticated using the required scope.

Conclusion

The Invoke-MgGraphRequest cmdlet is a versatile tool for advanced Microsoft Graph interactions. By leveraging it to fetch user data, administrators can efficiently handle scenarios that go beyond the capabilities of standard PowerShell cmdlets. With its flexibility and control, this cmdlet empowers you to create custom workflows and extend the functionality of Microsoft 365 management.