Get-MgUserByUserPrincipalName
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-MgBetaUserByUserPrincipalName
Syntax
Get (Default)
Get-MgUserByUserPrincipalName
-UserPrincipalName <String>
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-ResponseHeadersVariable <String>]
[-Headers <IDictionary>]
[<CommonParameters>]
GetViaIdentity
Get-MgUserByUserPrincipalName
-InputObject <IUsersIdentity>
[-ExpandProperty <String[]>]
[-Property <String[]>]
[-ResponseHeadersVariable <String>]
[-Headers <IDictionary>]
[<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 | Permissions (from least to most privileged) |
|---|---|
| Delegated (work or school account) | User.ReadBasic.All, User.ReadWrite.All, DeviceManagementManagedDevices.ReadWrite.All, User.Read.All, Directory.ReadWrite.All, Directory.Read.All, DeviceManagementServiceConfig.ReadWrite.All, DeviceManagementServiceConfig.Read.All, DeviceManagementConfiguration.ReadWrite.All, DeviceManagementManagedDevices.Read.All, DeviceManagementConfiguration.Read.All, DeviceManagementApps.ReadWrite.All, DeviceManagementApps.Read.All, |
| Delegated (personal Microsoft account) | Not supported |
| Application | User.ReadBasic.All, DeviceManagementApps.ReadWrite.All, User.Read.All, Directory.ReadWrite.All, Directory.Read.All, DeviceManagementServiceConfig.ReadWrite.All, User.ReadWrite.All, DeviceManagementManagedDevices.ReadWrite.All, DeviceManagementManagedDevices.Read.All, DeviceManagementConfiguration.ReadWrite.All, DeviceManagementConfiguration.Read.All, DeviceManagementServiceConfig.Read.All, DeviceManagementApps.Read.All, |
Parameters
-ExpandProperty
Expand related entities
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | Expand |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Headers
Optional headers that will be added to the request.
Parameter properties
| Type: | IDictionary |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-InputObject
Identity Parameter To construct, see NOTES section for INPUTOBJECT properties and create a hash table.
Parameter properties
| Type: | IUsersIdentity |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
GetViaIdentity
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Property
Select properties to be returned
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | Select |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ResponseHeadersVariable
Optional Response Headers Variable.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | RHV |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UserPrincipalName
Alternate key of user
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
Get
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
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[TimeZoneStandard <String>]: Usage: TimeZoneStandard='{TimeZoneStandard}'[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[UserPrincipalName <String>]: Alternate key of user[WindowsSettingId <String>]: The unique identifier of windowsSetting[WindowsSettingInstanceId <String>]: The unique identifier of windowsSettingInstance