Managing user accounts in a Microsoft 365 environment can quickly become overwhelming, especially for organizations with hundreds or thousands of employees. Fortunately, PowerShell provides robust tools for automating and streamlining these administrative tasks. Among these tools, the Get-MgUser cmdlet stands out as a powerful ally for IT professionals who need to query, filter, and manipulate user data in Azure Active Directory.
In this guide, we’ll explore the various ways to leverage Get-MgUser in your PowerShell scripts. Whether you’re looking to pull a comprehensive list of users, find specific individuals based on custom criteria, or export user data for reporting purposes, this cmdlet offers the flexibility and power you need. Let’s dive into the practical applications that will help you manage your Microsoft 365 environment more efficiently.
Get-MgUser Basics
The Get-MgUser cmdlet is part of the Microsoft Graph PowerShell SDK, which allows administrators to interact with Azure Active Directory through PowerShell. Before using this cmdlet, you must establish a connection to Microsoft Graph with appropriate permissions.
Here’s the general syntax of the Get-MgUser cmdlet:
Get-MgUser
-UserId <String>
-InputObject <IUsersIdentity>
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-Filter <String>]
[-Search <String>]
[-Sort <String[]>]
[-Top <Int32>]
[-ConsistencyLevel <String>]
[-PageSize <Int32>]
[-All]
[-CountVariable <String>]
[<CommonParameters>]
Getting Started: Connecting to Microsoft Graph
Before retrieving any user information, you must connect to Microsoft Graph with the correct permissions. For reading user data, the ‘User.Read.All’ scope is required:
Connect-MgGraph -Scopes 'User.Read.All'
This command prompts for authentication and requests consent to read user data.
Retrieving All Users from Azure AD
To get a complete list of all users in your Azure Active Directory, use:
Get-MgUser -All
The output provides essential user information including:
- DisplayName
- Id
- UserPrincipalName
Finding Specific Users by ID or Username
You can retrieve information about a specific user by providing either their UserPrincipalName or their unique ID:
# Get user by UserPrincipalName
Get-MgUser -UserId [email protected]
# Get user by ID
Get-MgUser -UserId cf634aac-d7d1-41a4-aad9-544c0bfda070
The output looks similar to this:
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
John Smith cf634aac-d7d1-41a4-aad9-544c0bfda070 [email protected] [email protected]
Counting Users in Azure AD
Sometimes you just need to know how many users you have in your directory. Here’s how to count them:
Get-MgUser -Count userCount -ConsistencyLevel eventual
This command returns user objects and stores the total count in the $userCount variable.
Retrieving All User Properties
The default output of Get-MgUser includes only the most commonly used properties. To see all available properties for a specific user, pipe the output to Format-List:
Get-MgUser -UserId '65bbf88c-ec92-417c-b7f1-fab8ecae7561' | Format-List
If you’re interested in specific properties only, use Select:
Get-MgUser -UserId 'cf634aac-d7d1-41a4-aad9-544c0bfda070' | Select Id, Mail, JobTitle
This gives you:
Id Mail JobTitle
-- ---- --------
cf634aac-d7d1-41a4-aad9-544c0bfda070 [email protected] Manager
Mastering Filters for Precise User Selection
The real power of Get-MgUser comes from its filtering capabilities. You can use operators like ‘eq’ (equals), ‘and’, ‘or’, and ‘startswith’ to narrow down your search.
Finding Users by Display Name
Get-MgUser -Filter "DisplayName eq 'John Smith'"
Finding Users by Department and Country
Get-MgUser -Filter "department eq 'Finance' and country eq 'United States'"
Retrieving Only Enabled User Accounts
Get-MgUser -Filter 'accountEnabled eq true' -All
Finding Users with Names Starting with Specific Letters
Get-MgUser -Filter "startsWith(DisplayName, 'J')"
Using Search for Flexible Matching
When you need more flexibility than what filters offer, the -Search parameter comes in handy:
Get-MgUser -Search 'DisplayName:joh' -ConsistencyLevel eventual
This finds all users whose display name contains “joh” (case-insensitive).
Exporting User Data to CSV
For reporting or documentation purposes, you might want to export user data to a CSV file:
Get-MgUser -All | Export-Csv -Path C:\Reports\azure_users.csv -NoTypeInformation
This command retrieves all users and saves their information to a CSV file that you can open in Excel or other spreadsheet applications.
Information You Can Retrieve with Get-MgUser
The Get-MgUser cmdlet provides access to a wealth of user information, including:
- Display Name
- ID
- Email Address
- Department
- Job Title
- Phone Number
- Creation Date and Time
- Office Location
- Country
- Manager
- License Assignments
This data is invaluable for user management, compliance reporting, and resource planning.
Conclusion
The Get-MgUser cmdlet provides IT administrators with a powerful toolset for managing Azure Active Directory users through PowerShell. From simple queries to complex filtering and data export, this cmdlet simplifies user management tasks that would otherwise be time-consuming through the Azure portal.
Mastering Get-MgUser allows you to automate routine administrative tasks, generate comprehensive reports, and gain better visibility into your organization’s user directory. Whether managing a small business or an enterprise with thousands of users, these PowerShell techniques will help you work more efficiently and maintain better control over your Azure AD environment.
For more advanced user management, consider exploring related cmdlets like New-MgUser for creating users and Set-MgUser for modifying existing user properties. With these tools at your disposal, you’ll be well-equipped to handle any user management scenario that comes your way.
Remember that great power comes with great responsibility—always test your scripts in a non-production environment first, and consider implementing safeguards to prevent accidental modification of critical user accounts.