Get-MgUser
Retrieve the properties and relationships of user object. This operation returns by default only a subset of the more commonly used properties for each user. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation for the user and specify the properties in a $select OData query option. Because the user resource supports extensions, you can also use the GET operation to get custom properties and extension data in a user instance. Customers through Microsoft Entra ID for customers can also use this API operation to retrieve their details.
Note
To view the beta release of this cmdlet, view Get-MgBetaUser
Syntax
Get-MgUser
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-Filter <String>]
[-Search <String>]
[-Sort <String[]>]
[-Top <Int32>]
[-ConsistencyLevel <String>]
[-ResponseHeadersVariable <String>]
[-Headers <IDictionary>]
[-PageSize <Int32>]
[-All]
[-CountVariable <String>]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Get-MgUser
-UserId <String>
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-ResponseHeadersVariable <String>]
[-Headers <IDictionary>]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Get-MgUser
-InputObject <IUsersIdentity>
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-ResponseHeadersVariable <String>]
[-Headers <IDictionary>]
[-ProgressAction <ActionPreference>]
[<CommonParameters>]
Description
Retrieve the properties and relationships of user object. This operation returns by default only a subset of the more commonly used properties for each user. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation for the user and specify the properties in a $select OData query option. Because the user resource supports extensions, you can also use the GET operation to get custom properties and extension data in a user instance. Customers through Microsoft Entra ID for customers can also use this API operation to retrieve their details.
Permissions
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | User.Read | User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Delegated (personal Microsoft account) | User.Read | User.ReadWrite |
Application | User.Read.All | User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Permissions
Permission type | Least privileged permissions | Higher privileged permissions |
---|---|---|
Delegated (work or school account) | User.ReadBasic.All | User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Delegated (personal Microsoft account) | Not supported. | Not supported. |
Application | User.Read.All | User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Examples
Example 1: Get the list of all the users
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -All | Format-List ID, DisplayName, Mail, UserPrincipalName
Id : e4e2b110-8d4f-434f-a990-7cd63e23aed6
DisplayName : Kristi Laar
Mail : Adams@contoso.com
UserPrincipalName : Adams@contoso.com
Id : dba12422-ac75-486a-a960-cd7cb3f6963f
DisplayName : Adele Vance
Mail : AdeleV@contoso.com
UserPrincipalName : AdeleV@contoso.com
This command returns a list of all users.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Example 2: Get a user by Id
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -UserId 'e4e2b110-8d4f-434f-a990-7cd63e23aed6' |
Format-List ID, DisplayName, Mail, UserPrincipalName
Id : e4e2b110-8d4f-434f-a990-7cd63e23aed6
DisplayName : Kristi Laar
Mail : Adams@contoso.com
UserPrincipalName : Adams@contoso.com
This command gets the specified user.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Example 3: Get a count of all users
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -Count userCount -ConsistencyLevel eventual
Id DisplayName Mail UserPrincipalName
-- ----------- ---- -----------------
00f9b5d4-290f-413d-ab86-feb3cdc23736 Johanna Lorenz JohannaL@Contoso.com JohannaL@Contoso.com
0568f35e-9177-4630-abd6-d533b21f1f78 Brian Johnson (TAILSPIN) BrianJ@Contoso.com BrianJ@Contoso.com
075b32dd-edb7-47cf-89ef-f3f733683a3f Patti Fernandez PattiF@Contoso.com PattiF@Contoso.com
0d005a1a-5e61-4388-bf5e-9060d727f891 Conf Room Baker Baker@Contoso.com Baker@Contoso.com
15516fb3-d57e-4d46-8aa9-8305bfd85b31 Enrico Cattaneo EnricoC@Contoso.com EnricoC@Contoso.com
180d5d54-159d-4970-ae07-99c8b658fa89 Allan Deyoung AllanD@Contoso.com AllanD@Contoso.com
185190a7-54f0-4892-add3-211c21327570 Debra Berger DebraB@Contoso.com DebraB@Contoso.com
The example gets a list of all users. The $userCount variable contains the count of the objects in the result. Advanced query requires the ConsistencyLevel parameter set to eventual
and the Count parameter in the command. For more information about ConsistencyLevel and Count, see Advanced query capabilities on Azure AD directory objects.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Example 4: Use -Filter and -Top to get one user with a display name that starts with 'a' including a count of returned objects
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -ConsistencyLevel eventual -Count userCount -Filter "startsWith(DisplayName, 'a')" -Top 1
Id DisplayName Mail UserPrincipalName UserType
-- ----------- ---- ----------------- --------
577a8b8a-ab84-4f90-a6cc-a62cd56010be Allan Deyoung AllanD@M365x814237.OnMicrosoft.com AllanD@M365x814237.OnMicrosoft.com Member
This example returns the top 1 users with the display name starting with 'a'. The $userCount variable contains the count of the objects in the result. Advanced query requires the ConsistencyLevel parameter set to eventual
and the Count parameter in the command. For more information about ConsistencyLevel and Count, see Advanced query capabilities on Azure AD directory objects.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Example 5: Use -Search to get all the users whose display name contains 'Conf' including a count of the returned users
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -ConsistencyLevel eventual -Count userCount -Search '"DisplayName:Conf"'
Id DisplayName Mail UserPrincipalName
-- ----------- ---- -----------------
0d005a1a-5e61-4388-bf5e-9060d727f891 Conf Room Baker Baker@Contoso.com Baker@Contoso.com
1e34292e-e5a3-46fd-9cac-8d37f2d3ab4a Conf Room Stevens Stevens@Contoso.com Stevens@Contoso.com
4aec2afd-be23-46d1-9138-f5ee6b77af5a Conf Room Crystal Crystal@Contoso.com Crystal@Contoso.com
82a56dfc-31f9-4b90-8a1c-6c4326bbffd9 Conf Room Hood Hood@Contoso.com Hood@Contoso.com
a7afe08d-55b9-4c44-be94-05d17c6513f3 Conf Room Rainier Rainier@Contoso.com Rainier@Contoso.com
This example returns all users whose display name contains 'Conf'. The $userCount variable contains the count of the objects in the result. Advanced query requires the ConsistencyLevel parameter set to eventual
and the Count parameter in the command. For more information about ConsistencyLevel and Count, see Advanced query capabilities on Azure AD directory objects.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Example 6: Use -Filter to get all the users with a display name that starts with 'Conf' including a count of the returned users, with the results ordered by UserPrincipalName
Connect-MgGraph -Scopes 'User.Read.All'
Get-MgUser -ConsistencyLevel eventual -Count userCount -Filter "startsWith(DisplayName, 'Conf')" -OrderBy UserPrincipalName
Id DisplayName Mail UserPrincipalName
-- ----------- ---- -----------------
0d005a1a-5e61-4388-bf5e-9060d727f891 Conf Room Baker Baker@Contoso.com Baker@Contoso.com
4aec2afd-be23-46d1-9138-f5ee6b77af5a Conf Room Crystal Crystal@Contoso.com Crystal@Contoso.com
82a56dfc-31f9-4b90-8a1c-6c4326bbffd9 Conf Room Hood Hood@Contoso.com Hood@Contoso.com
a7afe08d-55b9-4c44-be94-05d17c6513f3 Conf Room Rainier Rainier@Contoso.com Rainier@Contoso.com
1e34292e-e5a3-46fd-9cac-8d37f2d3ab4a Conf Room Stevens Stevens@Contoso.com Stevens@Contoso.com
This example filters all users whose display name starts with 'Conf' and orders the results by the user principal name. The $userCount variable contains the count of the objects in the result. Advanced query requires the ConsistencyLevel parameter set to eventual
and the Count parameter in the command. For more information about ConsistencyLevel and Count, see Advanced query capabilities on Azure AD directory objects.
To learn about other permissions for this resource, see the permissions reference.
To consent to any of these permissions run Connect-MgGraph -Scopes Permission
. For example, Connect-MgGraph -Scopes User.ReadBasic.All, User.Read.All
.
Parameters
-All
List all pages.
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConsistencyLevel
Indicates the requested consistency level. Documentation URL: https://docs.microsoft.com/graph/aad-advanced-queries
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CountVariable
Specifies a count of the total number of items in a collection. By default, this variable will be set in the global scope.
Type: | String |
Aliases: | CV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ExpandProperty
Expand related entities
Type: | String[] |
Aliases: | Expand |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Filter
Filter items by property values
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Headers
Optional headers that will be added to the request.
Type: | IDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-InputObject
Identity Parameter To construct, see NOTES section for INPUTOBJECT properties and create a hash table.
Type: | IUsersIdentity |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-PageSize
Sets the page size of results.
Type: | Int32 |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProgressAction
{{ Fill ProgressAction Description }}
Type: | ActionPreference |
Aliases: | proga |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Property
Select properties to be returned
Type: | String[] |
Aliases: | Select |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ResponseHeadersVariable
Optional Response Headers Variable.
Type: | String |
Aliases: | RHV |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Search
Search items by search phrases
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Sort
Order items by property values
Type: | String[] |
Aliases: | OrderBy |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Top
Show only the first n items
Type: | Int32 |
Aliases: | Limit |
Position: | Named |
Default value: | 0 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UserId
The unique identifier of user
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
Microsoft.Graph.PowerShell.Models.IUsersIdentity
System.Collections.IDictionary
Outputs
Microsoft.Graph.PowerShell.Models.IMicrosoftGraphUser
Notes
COMPLEX PARAMETER PROPERTIES
To create the parameters described below, construct a hash table containing the appropriate properties. For information on hash tables, run Get-Help about_Hash_Tables.
INPUTOBJECT <IUsersIdentity>
: Identity Parameter
[AttachmentBaseId <String>]
: The unique identifier of attachmentBase[AttachmentSessionId <String>]
: The unique identifier of attachmentSession[ChecklistItemId <String>]
: The unique identifier of checklistItem[DirectoryObjectId <String>]
: The unique identifier of directoryObject[ExtensionId <String>]
: The unique identifier of extension[LicenseDetailsId <String>]
: The unique identifier of licenseDetails[LinkedResourceId <String>]
: The unique identifier of linkedResource[OAuth2PermissionGrantId <String>]
: The unique identifier of oAuth2PermissionGrant[OutlookCategoryId <String>]
: The unique identifier of outlookCategory[ProfilePhotoId <String>]
: The unique identifier of profilePhoto[ServiceStorageQuotaBreakdownId <String>]
: The unique identifier of serviceStorageQuotaBreakdown[SharedInsightId <String>]
: The unique identifier of sharedInsight[TodoTaskId <String>]
: The unique identifier of todoTask[TodoTaskListId <String>]
: The unique identifier of todoTaskList[TrendingId <String>]
: The unique identifier of trending[UsedInsightId <String>]
: The unique identifier of usedInsight[UserId <String>]
: The unique identifier of user[WindowsSettingId <String>]
: The unique identifier of windowsSetting[WindowsSettingInstanceId <String>]
: The unique identifier of windowsSettingInstance