Get-MgUser – Find Azure AD Users and Filter using PowerShell Script. Are you tired of manually sifting through the Azure portal to find the necessary user information? Look no further than the Get-MgUser cmdlet.
This powerful cmdlet (part of the Microsoft.Graph.Users module) lets you quickly locate and filter Azure AD users based on specific criteria, saving countless administrative time.
In this article, I go into the details of the Get-MgUser cmdlet. In the process, you learn how to use this all powerful cmdlet to get any information about Azure AD users.
This guide explains the tools you need to take your Azure AD user reporting to the next level.
Let’s start article blog Get-MgUser – Find Azure AD Users and Filter using PowerShell Script.
Install the Required Modules and Sign in to Azure AD
So, Get-MgUser cmdlet is part of the Microsoft.Graph.Users module. So, if you haven’t already installed this module, follow the steps in our article, Get-MgUserMemberOf – List Group Memberships of an Azure AD User using PowerShell to install the Microsoft.Graph.Users PowerShell Module (steps 1 and 2 of the first section of the article).
Once you have installed the module, run the command below to connect sign in to your Azure AD account with Microsoft Graph PowerShell.
Connect-MgGraph -Scopes 'User.Read.All'
When you sign in to Azure AD with Microsoft Graph PowerShell, you must define the scope that determines the permission you need to perform tasks in Azure AD. In the above command, the “User.Read.All” scope gives you the permission you need to “read” (display) user information in Azure AD.
Running the Connect-MgGraph prompts PowerShell to display a sign in dialogue box. Enter your Azure AD into the first screen and click Next.
The next screen prompts you to enter the password for the Azure AD account. Enter the password and Sign in.
If you followed the steps in this guide correctly, you should successfully sign in to your Azure AD and PowerShell should return to its prompt. See the screenshot below for a reference.
Understanding Syntaxes and Parameters of the Get-MgUser Cmdlet
This guide is a “deep dive,” so I want to take you “behind the scene” of the Get-MgUser cmdlet. The syntax of the command shows you how to run the command, while its parameters show you all available options to manipulate the command.
Learning the syntaxes and parameters of the Get-MgUser cmdlet equips you to use it to find Azure AD users using different filtering parameters in PowerShell commands and scripts.
Syntaxes of the Get-MgUser Cmdlet
The Get-MgUser Cmdlet has three syntaxes. To see all the syntaxes, execute the Get Help command shown below.
(Get-Help Get-MgUser).syntax
The command confirms that the Get-MgUser has three syntaxes. Below is a screenshot for your reference.
Get-MgUser
[-ExpandProperty (String[])]
[-Property (String[])]
[-Filter (String)]
[-Search (String)]
[-Skip (Int32)]
[-Sort (String[])]
[-Top (Int32)]
[-ConsistencyLevel (String)]
[-PageSize (Int32)]
[-All]
[-CountVariable (String)]
[(CommonParameters)]
Get-MgUser
-UserId (String)
[-ExpandProperty (String[])]
[-Property (String[])]
[(CommonParameters)]
Get-MgUser
-InputObject (IUsersIdentity)
[-ExpandProperty (String[])]
[-Property (String[])]
[(CommonParameters}]
To avoid doubt, the three syntaxes above mean you run the Get-MgUser command in three ways. To understand the syntaxes, the first step is to note the parameters that differentiate them.
In this regard, the parameter unique to the first syntax is the Filter parameter. Similarly, UserID is unique to the second syntax, while InputObject is unique to the third one.
With their differentiating parameters noted, the next significant bit is noting parameters common to the three syntaxes. Looking at the syntaxes, you note that ExpandProperty and Property are common to them.
Pointing out also, the first syntax has additional parameters worthy of note. I explain the parameters of the three syntaxes in the following subsection.
Try our Azure AD User Reporting & Auditing Tools. (SaaS Solution)
Try us out for Free, Access to all features. – 200+ AD Report templates Available. Easily customise your own AD reports.
The Parameters of the Get-MgUser Cmdlet Explained
| Get-MgUser Parameter Name | Parameter Info | Notes |
|---|---|---|
|
Filter |
Use the Filter parameter to filter items by property values. |
The Filter parameter is only available in the first syntax. Furthermore, you cannot use it with the UserID and/or InputObject parameters. |
|
UserID |
All Azure AD objects, including users has a unique ID. When you specify the UserID parameter, enter the UserID (Id) for the user you wish to return information about using the Get-MgUser command. |
The UserID parameter is only available in the second syntax and you cannot combine this parameter with either the Filer and/or InputObjject parameters. |
|
InputObject |
The InputObject parameter gives you the ability to use available Identity properties to construct a hashtable. For a full list of available properties, see the NOTES section of the online information of the Get-MgUser command. |
You can only use this parameter in the third syntax but cannot combine it with the Filter and/or UserID parameters. |
|
ExpandProperty |
When you run the Get-MgUser command, it may return a group of properties. In this instance, you can use the ExpandProperty parameter to display all the properties in the group. |
The ExpandProperty parameter is available in the three syntaxes of the command. |
|
Property |
The Property parameter is useful if you want to return certain properties of users. Use this parameter to list the properties you wish to return. |
Like the ExpandProperty parameter, the Property parameter is available in the three syntaxes of the Get-MgUser command. |
|
Search |
Use the Search parameter to search for items by property. |
To use the Search parameter, you must include the ConsistencyLevel parameter with a value of "eventual." Additionally, you have to specify the search criteria in the format "property: propertyvalue." The Search parameter is only available in the first syntax. |
|
ConsistencyLevel |
The ConsistencyLevel parameter is rerquired when you perform advanced queries like using the Search parameter. |
The common value for this parameter is "eventual" specified as "-ConsistencyLevel: eventual" (without the quotes). To read more about consistency levels, visit Advanced query capabilities on Azure AD objects. The ConsistencyLevel parameter is only available in the first syntax of the Get-MgUser command. |
|
Skip |
This parameter is useful if you want to skip the first n items in a result. |
Skip is available in the first syntax. |
|
Sort |
Use Sort to order items in the result returned by property values. |
The Sort parameter is only available in the first syntax. So, you cannot use it with the UserID or InputObject parameters. |
|
Top |
Use the Top parameter to show only the first n items in a query result. |
Top is similar to Skip in that they both determine the items returned. However, while you use Top to return the first n items, you use Skip to skip the first n items. |
|
PageSize |
Use this parameter to specify the page size of the result. This affects the number of items returned by the result. |
PageSize is also only available in the first syntax. |
|
All |
When you specify the All parameter, you instruct the Get-MgUser cmdlet to list all pages. |
The All parameter overriders the PageSize parameter. So, if you use both in the same command, the command returns all pages and ignores the number you specify in the PageSize parameter. |
I omitted the CommonParameters in the table because it is a set of parameters common to most PowerShell cmdlets. To read more about these parameters, visit the about_CommonParameters page.
Examples, Applications of Using Get-MgUser to Find, Filter Azure AD Users with PowerShell
So far, the article Get-MgUser – Find Azure AD Users and Filter using PowerShell Script, has covered the steps to install the PowerShell modules you require to run the Get-MgUser command. Furthermore, I have also shown you how to sign in to Azure AD from Microsoft Graph PowerSell.
Not only that, but I have also read the syntax and parameters of the Get-MgUser command.
It is now time to put the knowledge to use. In this section, I show various PowerShell scripts to use the Get-MgUser command to find and filter Azure AD users.
Get a List of All Azure AD Users with Get-MgUser
To return a list of all users in Azure and display the default properties, run the command below:
Get-MgUser -All
The command is not especially useful as it displays the default values – Id, DisplayName, Mail, and UserPrincipalName.
To bypass the default and return properties you require, pipe Get-MgUser to Select-Object; then list the properties you want to return. In my sample command below, I am returning DisplayName, Mail, and UserPrincipalName.
Get-MgUser | Select-Object DisplayName, Mail, UserPrincipalName
In the last command, I displayed the result in a table. I could format the result to display in a list. To achieve this, instead of piping the first command to Select-Object, I will pipe it to Format-List instead.
Here is the modified command. Screenshot below.
Get-MgUser | Select-Object DisplayName, Mail, UserPrincipalName
If unsure what properties to select, pipe the Get-MgUser command with the All parameter to Get-Member:
Get-MgUser -All | Get-Member
Find an Azure AD User with Get-MgUser by Specifung the UserID Parameter
Get-MgUser -UserId "Id"
Change Id to the user’s ID. This time, my command returns one user.
Use Get-MgUser to Find Azure AD Users with a Specified DisplayName
If you need to find Azure AD users with a DisplayName, use the Filter parameter. This parameter accepts the standard PowerShell operators, eq, and, or.
Additionally, the Filter parameter accepts the the startswith operator.
Command below uses the Filter parameter to return all users with “Victor Ashiedu” as their DisplayName.
Get-MgUser -Filter "displayname eq 'Victor Ashiedu'"
In my example, three users meet my filter criteria.
Find All Disabled Azure AD Users
Get-MgUser -All -Filter 'accountEnabled eq false'
On the opposite side of the coin, to find all enabled users, replace “false” with “true.”
Get-MgUser -All -Filter 'accountEnabled eq true'
How to Combine the "Search" and "Filter" Parameters in Get-MgUser
In the last two examples, I used the Filter parameter to search for users based on their DisplayName and account status. It may interest you that you can combine the Filter and Search parameters.
In this example, I search for a user whose DisplayName contains “Victor” and whose account status us “Enabled.” Here is the command:
Get-MgUser -All -Filter 'accountEnabled eq true' -Search 'DisplayName:victor' -ConsistencyLevel eventual
If you look closely, you note that I included the ConsistencyLevel parameter with a value of “eventual.” This parameter is required if you use the Search parameter.
Calling the Search parameter without including the ConsistencyLevel parameter throws the error message “Get-MgUser : Request with $search query parameter only works through MSGraph with a special request header: ‘ConsistencyLevel: eventual.’“
See my screenshot below for the last command’s result and the error message generated when I ran the command without the ConsistencyLevel parameter.
Thank you for reading Get-MgUser – Find Azure AD Users and Filter using PowerShell Script. We shall conclude the article now.
Get-MgUser - Find Azure AD Users and Filter using PowerShell Script Conclusion
The Get-MgUser cmdlet is a powerful tool Azure AD SysAdmins use to find users. The cmdlet has numerous parameters for filtering and advanced search.
Although this is a powerful cmdlet, remember you must install the Microsoft.Graph.Users module on your PC to use the command. Not only that, but you must also sign into Azure AD with the Connect-MgGraph command.
Once you meet these two prerequisites and have the required permissions, you use the Get-MgUser cmdlet to query Azure AD to return different user information.
Try InfraSOS for FREE
Invite your team and explore InfraSOS features for free
- Free 15-Days Trial
- Easy Setup
- Full Access to Enterprise Plan
