Table of Contents
The Get-MgUser cmdlet in Microsoft Graph PowerShell allows you to find information on a user, group of users or all users within your organisation from the command line. It will also expose more information about your users than you can normally find through web-based management portals such as the Azure AD admin Center or Microsoft 365 admin center.
In this tutorial, I am going to walk you through how to use the Get-MgUser cmdlet in Microsoft Graph PowerShell to find and export useful information about your users. I will also cover how you can filter and manipulate your search results to find the specific information you need.
Why use the Get-MgUser cmdlet?
Get-MgUser is the preferred command to use to find information about your users through a command line interface. The command is found within the Microsoft Graph PowerShell SDK which is the successor to PowerShell modules such as MSOnline and AzureAD.
There are many different parameters your can use with Get-MgUser, such as:
-ExpandProperty <String[]>
-Property <String[]>
-Filter <String>
-Search <String>
-Skip <Int32>
-Sort <String[]>
-Top <Int32>
-ConsistencyLevel <String>
-PageSize <Int32>
-All
-CountVariable <String>Finding the required permissions to run Get-MgUser
Before you connect to Microsoft Graph, you must ensure you use the -scope parameter with the correct permissions defined to run the command.
To find the minimum level of permissions you need to find information on your user, use the Find-MgGraphCommand cmdlet to find permissions for the Get-MgUser cmdlet.
Find-MgGraphCommand -Command Get-MgUser | Select -First 1 -ExpandProperty PermissionsYou do not need to be connected to your organisation to run this command however you do need to have Microsoft Graph PowerShell installed. Here is the expected output, although the description does not show, assumptions can be made accurately based on the permission name.
PS C:\> Find-MgGraphCommand -Command Get-MgUser | Select -First 1 -ExpandProperty Permissions
Name IsAdmin Description
---- ------- -----------
DeviceManagementApps.Read.All True Read Microsoft Intune apps
DeviceManagementApps.ReadWrite.All True Read and write Microsoft Intune apps
DeviceManagementManagedDevices.Read.All True Read devices Microsoft Intune devices
DeviceManagementManagedDevices.ReadWrite.All True Read and write Microsoft Intune devices
DeviceManagementServiceConfig.Read.All True Read Microsoft Intune configuration
DeviceManagementServiceConfig.ReadWrite.All True Read and write Microsoft Intune configuration
Directory.AccessAsUser.All True Access the directory as you
Directory.Read.All True Read directory data
Directory.ReadWrite.All True Read and write directory data
User.Read.All True Read all users' full profiles
User.ReadBasic.All False Read all users' basic profiles
User.ReadWrite.All True Read and write all users' full profilesBased on the above output, in order to run our command, we can use the following command to connect to Microsoft Graph with the least permissions required.
Connect-MgGraph -Scopes 'User.Read.All'Find information on a single user
To find the information of a single user, you can run the following command to show a list of all users’ display names, usernames and Ids. From here you can copy the Id for your target user to allow you to target that user directly.
Get-MgUser | Select DisplayName, UserPrincipalName, IdPS C:\> Get-MgUser | Select DisplayName, UserPrincipalName, Id
DisplayName UserPrincipalName Id
----------- ----------------- --
Bon Ben [email protected] 4f146ecb-f495-4e30-b510-15995e59ffc1
Ben [email protected] 4091c7f3-10ff-4407-856c-a95d141e05b9
Chris [email protected] 617660b7-8595-42d1-94d7-57de2373b56a
Info [email protected] 953fc411-c599-432e-950c-2fe60199991a
Marketing [email protected] 09e6ce83-c85a-4209-bc2f-71268bbd0f56
Max [email protected] ed386a96-b09a-40f6-9bbc-c40474a10993
Noreply [email protected] 6887ed47-bb24-46fb-b2e9-08555e8631db
Tonny [email protected] 6e19de25-fbbf-4faf-9a16-246f21f8c44f
VIP01 [email protected] 6fb331a4-5779-4fdc-92fe-1c7583177593Once you have copied the user ID, place it into the following command to display all information on a user account.
Get-MgUser -UserId 4091c7f3-10ff-4407-856c-a95d141e05b9 | FLIf you already know the username of your user, you can replace the Id with the username instead for the same result.
Get-MgUser -UserId [email protected] | FLSelecting specific properties
When you target a specific user and include the ‘format list’ parameter, you get pages of information, where most of it is empty or irrelevant. Using the select parameter, we can select the attributes that are displayed.
For example, to only display the display name, username and user id, we can use the following command.
Get-MgUser -UserId [email protected] | Select DisplayName, UserprincipalName, IdPS C:\> Get-MgUser -UserId [email protected] | Select DisplayName, UserprincipalName, Id
DisplayName UserPrincipalName Id
----------- ----------------- --
Ben [email protected] 4091c7f3-10ff-4407-856c-a95d141e05b9Some of the properties you wish you view may not be immediately visible, this is because they are nested. For example, if you want to view if a user has automatic replies enabled on their mailbox, you can run the following.
PS C:\> Get-MgUser -UserId [email protected] | Select DisplayName, UserprincipalName, Manager | FL
DisplayName : Ben
UserPrincipalName : [email protected]
Manager : Microsoft.Graph.PowerShell.Models.MicrosoftGraphDirectoryObject Get-MgUser -UserId '[email protected]' -Property MailboxSettings | `
Select @{Name = 'AutomaticReply'; Expression = {$_.MailboxSettings.AutomaticRepliesSetting.status}}It’s not easy to find these settings sometimes, however, the Microsoft Graph documentation is the best place to start when you need to extract specific information.
Find nested properties with the Microsoft Graph
Many of the properties when calling the Get-MgUser cmdlet are nested. This is also true of other cmdlets in the Microsoft Graph and to find these properties the Graph API reference documentation on Microsoft Learn is the best place to look.
In the example above where I found the automatic reply settings for a mailbox, we can look this up in the documentation as follows.
Start by going to https://learn.microsoft.com/graph/api/resources/user#properties, this page shows all the properties, the value type and an explanation of each property.
Find the initial property and select the type field if it is clickable. Here I selected mailboxSettings
We can see that if we want to view the status of the autoreply settings on a user’s mailbox, we need the status attribute. Which is nested in MailboxSettings > AutomaticReplySettings.
So we know that our setting value is located in MailboxSettings.AutomaticRepliesSetting.status, however, this must be included in our command as an expression. Failing to do so and you will get an error like the following: Select : A mandatory entry for expression is missing.
So to make this work, once we have defined the -property parameter in our command we can PIPE, then use the select command to extract our value, as follows:
Find hidden information with -ExpandProperty or -Expand
If you have used the format-list command to view all user attributes for a user, you may have found that many are empty. I am not sure why this is, but some may certainly contain information. You can use either the Expand or ExpandProperty parameters to display information that was not immediately visible.
PS C:\> Get-MgUser -UserId [email protected] | Select DisplayName, Id, SignInActivity | fl
DisplayName : Ben
Id : 4091c7f3-10ff-4407-856c-a95d141e05b9
SignInActivity : Microsoft.Graph.PowerShell.Models.MicrosoftGraphSignInActivityAnother unusual quirk is that not all commands will accept the user username after Get-MgUser, hence why at the start of tutorial, I highlighted you can either parse the UserPricincipalName or the Id into your command. This is true of the next command I am going to show you.
For example, to display the last sign-in information for a user, you can do the following.
PS C:\> $userid = (Get-MgUser -UserId '[email protected]').id
PS C:\> Get-MgUser -Userid $userid -Property SignInActivity | Select-Object -ExpandProperty SignInActivity | FL
LastNonInteractiveSignInDateTime : 2/2/2023 2:06:47 AM
LastNonInteractiveSignInRequestId : d8fa780f-c164-4606-b8c1-23d4702af000
LastSignInDateTime : 2/2/2023 2:06:46 AM
LastSignInRequestId : 6830f9e6-5be4-4e7d-a381-1cfbef0fc300
AdditionalProperties : {}You can see in the above command, without knowing the user’s Id, we have selected the Id property and called the user twice within our command. If you do not specify the id in your command, you will get an error like the following:
PS C:\> Get-MgUser -UserId '[email protected]' -Property SignInActivity | Select-Object -ExpandProperty SignInActivity | FL
Get-MgUser :
{"@odata.context":"http://reportingservice.activedirectory.windowsazure.com/$metadata#Edm.String","value":"Get By Key
only supports UserId and the key has to be a valid Guid"}
At line:1 char:1
+ Get-MgUser -userid [email protected] -property signinactivity | Select-Obj ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: ({ UserId = [email protected] = }:<>f__AnonymousType10`3) [Get-MgUser
_Get], RestException`1
+ FullyQualifiedErrorId : UnknownError,Microsoft.Graph.PowerShell.Cmdlets.GetMgUser_GetAs such, to use the same command above with the user id, you can run the following.
PS C:\> Get-MgUser -Userid 4091c7f3-10ff-4407-856c-a95d141e05b9 -Property SignInActivity | `
>> Select-Object -ExpandProperty SignInActivity | FL
LastNonInteractiveSignInDateTime : 2/2/2023 2:06:47 AM
LastNonInteractiveSignInRequestId : d8fa780f-c164-4606-b8c1-23d4702af000
LastSignInDateTime : 2/2/2023 2:06:46 AM
LastSignInRequestId : 6830f9e6-5be4-4e7d-a381-1cfbef0fc300
AdditionalProperties : {}You will find that not all attributes are presented in the same format. This means that information cannot always be extracted in the same way. For example, if we want to view the name of the manager for a specific user, we can run the following command.
PS C:\> Get-MgUser -UserId '[email protected]' -ExpandProperty Manager | `
>> Select @{Name = 'Manager'; Expression = {$_.Manager.AdditionalProperties.displayName}}
Manager
-------
ChrisGet-MgUser -UserId '[email protected]' -ExpandProperty Manager | `
Select @{Name = 'Manager'; Expression = {$_.Manager.AdditionalProperties.displayName}} Get-MgUser -UserId '[email protected]' -Property MailboxSettings | `
Select @{Name = 'AutomaticReply'; Expression = {$_.MailboxSettings.AutomaticRepliesSetting.status}}Filter Get-MgUser search results
You can use the -Filter parameter to filter search results for your users. When using the filter parameter there are only a few logical operators you can use, these are:
- eq The attribute is equal to
- le The attribute is less than or equal to (alphabetically)
- gt The attribute is greater than or equal to (alphabetically)
- and Attribute 1 is equal to and attribute 2 is equal to
- or Attribute 1 is equal to or attribute 2 is equal to
- startswith The property start with
- endswith The property ends with
Below I will show you an example of how to use each of the logical operators in your commands.
To start we can use the eq operator to find users with attributes that match a specific value, here will filter for users with a display name equal to ‘John Smith’.
PS C:\> Get-MgUser -Filter "DisplayName eq 'Chris'"
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
617660b7-8595-42d1-94d7-57de2373b56a Chris [email protected] [email protected] MemberIn a similar format to the above, we can use the le or ge operator to find users whose display name starts with a letter less or greater than ‘G’ in the alphabet.
#Filter users whos name begins with a letter before C in the alphabet
PS C:\> Get-MgUser -Filter "DisplayName le 'c'"
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- ------
4091c7f3-10ff-4407-856c-a95d141e05b9 Ben [email protected] [email protected] Member
4f146ecb-f495-4e30-b510-15995e59ffc1 Bon Ben [email protected] [email protected] Member
#Filter users whos name begins with a letter after C in the alphabet
PS C:\> Get-MgUser -Filter "DisplayName ge 'c'"
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
617660b7-8595-42d1-94d7-57de2373b56a Chris [email protected] [email protected] Member
6fb331a4-5779-4fdc-92fe-1c7583177593 VIP01 [email protected] [email protected] Member
6887ed47-bb24-46fb-b2e9-08555e8631db Noreply [email protected] [email protected] Member
ed386a96-b09a-40f6-9bbc-c40474a10993 Max [email protected] [email protected] Member
953fc411-c599-432e-950c-2fe60199991a Info [email protected] [email protected] Member
09e6ce83-c85a-4209-bc2f-71268bbd0f56 Marketing [email protected] [email protected] Member
6e19de25-fbbf-4faf-9a16-246f21f8c44f Tonny [email protected] [email protected] MemberTo find all users in your tenant who’s display name starts with the letter D, you can use the startswith operator.
PS C:\> Get-MgUser -Filter "startswith(Displayname, 'b')"
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- ------
4091c7f3-10ff-4407-856c-a95d141e05b9 Ben [email protected] [email protected] Member
4f146ecb-f495-4e30-b510-15995e59ffc1 Bon Ben [email protected] [email protected] MemberSimilar to the above, we can the user endswith operator to find users whose primary mail address ends with a specific domain name. For this command it is important we specify the -CountVariable and -ConsistencyLevel parameters.
PS C:\> Get-MgUser -CountVariable CountVar -Filter "endsWith(mail,'ez365.me')" -ConsistencyLevel eventual
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
09e6ce83-c85a-4209-bc2f-71268bbd0f56 Marketing [email protected] [email protected] Member
4091c7f3-10ff-4407-856c-a95d141e05b9 Ben [email protected] [email protected] Member
4f146ecb-f495-4e30-b510-15995e59ffc1 Bon Ben [email protected] [email protected] Member
617660b7-8595-42d1-94d7-57de2373b56a Chris [email protected] [email protected] Member
6887ed47-bb24-46fb-b2e9-08555e8631db Noreply [email protected] [email protected] Member
6e19de25-fbbf-4faf-9a16-246f21f8c44f Tonny [email protected] [email protected] Member
6fb331a4-5779-4fdc-92fe-1c7583177593 VIP01 [email protected] [email protected] Member
953fc411-c599-432e-950c-2fe60199991a Info [email protected] [email protected] Member
ed386a96-b09a-40f6-9bbc-c40474a10993 Max [email protected] [email protected] MemberThe above commands can now be paired up with the and operator to fine-tune our results. For example, to find users who have the main domain of ez365.me and display name that starts with a T.
PS C:\> Get-MgUser -All -CountVariable CountVar `
>> -Filter "endsWith(mail,'ez365.me') and startswith(Displayname, 'T')" -ConsistencyLevel eventual
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
6e19de25-fbbf-4faf-9a16-246f21f8c44f Tonny [email protected] [email protected] MemberFind users with the search parameter
Similar to the filter option, we can also use the -search parameter to fine-tune our user search results. I mentioned above about using the -ConsistencyLevel option and setting to eventual, we will need to do this in the following commands.
Below we are searching for users with a display name that start with the letter T.
PS C:\> Get-MgUser -ConsistencyLevel eventual -Search '"DisplayName:T"'
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
6e19de25-fbbf-4faf-9a16-246f21f8c44f Tonny [email protected] [email protected] MemberWhen using the Get-MgUser cmdlet, the search and filter parameters are not mutually exclusive, although arguably with the lack of features/documentation, it does not bring a whole load of benefits to combine the two, however you can.
For example, if you want to filter for all users with the domain ez365.me and search the results for users in a particular department, you could run the following.
Get-MgUser -All `
-Filter "endsWith(mail,'ez365.me')" `
-Search 'Department:Marketing' -ConsistencyLevel eventual
