Manage users
Users are the representation of a Microsoft Entra work or school user account or a personal Microsoft account in Microsoft Entra ID. The user resource in Microsoft Entra PowerShell is the representation of a user, and includes relationships and resources that are relevant to the user.
The user resource provides a straightforward way for you to access and manipulate user resources without having to perform extra calls, look up specific authentication information, and directly issue queries against other Microsoft Entra PowerShell objects.
Prerequisites
To manage users with Microsoft Entra PowerShell, you need:
- A Microsoft Entra user account. If you don't already have one, you can Create an account for free.
- One of the following roles: User Administrator, or Group Administrator.
- Microsoft Entra PowerShell module installed. Follow the Install the Microsoft Entra PowerShell module guide to install the module.
You can access a user's information and manage their data on their behalf or as an app with its own identity.
Create a user and manage a user's password
To manage users, you can perform the following common user management tasks:
Create a user
This example creates a new user.
Connect-Entra -Scopes 'User.ReadWrite.All'
$passwordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$passwordProfile.Password = '<Strong-Password>'
$userParams = @{
DisplayName = 'New User'
PasswordProfile = $passwordProfile
UserPrincipalName = 'NewUser@contoso.com'
AccountEnabled = $true
MailNickName = 'NewUser'
}
New-EntraUser @userParams
The output displays details of the newly created user.
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
New User aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb NewUser@contoso.com
Manage user password
To update a user's password by administrator, use this command:
Connect-Entra -Scopes 'Directory.AccessAsUser.All' $newPassword = '<strong-password>' $securePassword = ConvertTo-SecureString $newPassword -AsPlainText -Force Set-EntraUserPassword -UserId 'SawyerM@contoso.com' -Password $securePasswordTo update the password for the signed-in user (self-serve), use this command:
Connect-Entra -Scopes 'Directory.AccessAsUser.All' $currentPassword = ConvertTo-SecureString '<strong-password>' -AsPlainText -Force $newPassword = ConvertTo-SecureString '<strong-password>' -AsPlainText -Force Update-EntraSignedInUserPassword -CurrentPassword $currentPassword -NewPassword $newPasswordThis command allows users to change their own passwords without admin privileges.
Search users
To search for a user by
mailNickname, use this command:Connect-Entra -Scopes 'User.Read.All' Get-EntraUser -Filter "startswith(MailNickname,'AdeleV')"The output shows user details based on a
mailNicknamesearch.DisplayName Id Mail UserPrincipalName ----------- -- ---- ----------------- Adell Vance aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb adelev@contoso.com adelev@contoso.comTo search for a user by
userPrincipalName, use this command:Connect-Entra -Scopes 'User.Read.All' Get-EntraUser -Filter "userPrincipalName eq 'SawyerM@contoso.com'"The output shows user details based on a
userPrincipalNamesearch.DisplayName Id Mail UserPrincipalName ----------- -- ---- ----------------- Sawyer Miller aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb SawyerM@contoso.com SawyerM@contoso.comTo search for users with the job title of
Retail manager, use this command:Connect-Entra -Scopes 'User.Read.All' Get-EntraUser -Filter "jobTitle eq 'Retail Manager'"The output shows user details based on a
jobTitlesearch.DisplayName Id Mail UserPrincipalName ----------- -- ---- ----------------- Sawyer Miller aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb SawyerM@contoso.com SawyerM@contoso.comTo search for users in Marketing department, use this command:
Connect-Entra -Scopes 'User.Read.All' Get-EntraUser -Filter "department eq 'Marketing'"The output shows user details based on a
departmentsearch.DisplayName Id Mail UserPrincipalName ----------- -- ---- ----------------- Adell Vance aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb adelev@contoso.com adelev@contoso.com Christie Cline bbbbbbbb-1111-2222-3333-cccccccccccc christiec@contoso.com christiec@contoso.comTo find the five most recently created users, use this command:
Connect-Entra -Scopes 'User.Read.All' Get-EntraUser -All | Sort-Object -Property createdDateTime -Descending | Select-Object -First 5The output lists recently deleted users.
DisplayName Id Mail UserPrincipalName ----------- -- ---- ----------------- Adell Vance aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb adelev@contoso.com adelev@contoso.com Christie Cline bbbbbbbb-1111-2222-3333-cccccccccccc christiec@contoso.com christiec@contoso.com Sawyer Miller cccccccc-2222-3333-4444-dddddddddddd sawyerm@contoso.com sawyerm@contoso.com Kez Michael hhhhhhhh-7777-8888-9999-iiiiiiiiiiii KezM@contoso.com KezM@contoso.com Avery Smith eeeeeeee-4444-5555-6666-ffffffffffff AveryS@contoso.com AveryS@contoso.com
Retrieve a user's sign-in activity
The following example shows how to retrieve the sign-in activity of a specific user.
Connect-Entra -Scopes 'User.Read.All','AuditLog.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com' -Property 'SignInActivity' |
Select-Object -Property Id, DisplayName, UserPrincipalName -ExpandProperty 'SignInActivity'
The output shows the user's sign-in activity.
lastNonInteractiveSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastSignInRequestId : cccccccc-2222-3333-4444-dddddddddddd
lastSuccessfulSignInDateTime : 9/9/2024 1:12:13 PM
lastNonInteractiveSignInDateTime : 9/9/2024 1:12:13 PM
lastSuccessfulSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastSignInDateTime : 9/7/2024 9:15:41 AM
id : aaaaaaaa-bbbb-cccc-1111-222222222222
displayName : Sawyer Miller
userPrincipalName : SawyerM@contoso.com
List a user's group memberships
The following example lists the groups that a user is a member of.
Connect-Entra -Scopes 'User.Read'
Get-EntraUserMembership -UserId 'SawyerM@contoso.com' |
Select-Object Id, displayName, createdDateTime, '@odata.type' |
Format-Table -AutoSize
The output shows the user's memberships.
Id displayName createdDateTime @odata.type
-- ----------- --------------- -----------
00aa00aa-bb11-cc22-dd33-44ee44ee44ee Contoso 2024-10-06T08:49:16Z #microsoft.graph.group
22cc22cc-dd33-ee44-ff55-66aa66aa66aa Contoso marketing 2024-10-07T01:17:28Z #microsoft.graph.group
55ff55ff-aa66-bb77-cc88-99dd99dd99dd Pacific Admin Unit #microsoft.graph.administrativeUnit
Use these commands to list the entities a user belongs to:
- Get-EntraUserAdministrativeUnit - to retrieve a list of administrative units to which a user belongs.
- Get-EntraUserGroup - to retrieve a list of groups a user belongs to.
- Get-EntraUserRole - to retrieve a list of directory roles assigned to a user.
Get a user's manager, direct reports and assign a manager to a user
Get a user's manager.
Connect-Entra -Scopes 'User.Read.All' Get-EntraUserManager -UserId 'SawyerM@contoso.com' | Select-Object Id, displayName, userPrincipalName, createdDateTime, accountEnabled, userType | Format-Table -AutoSizeThe output shows the user's manager.
id displayName userPrincipalName createdDateTime accountEnabled userType -- ----------- ----------------- --------------- -------------- -------- 11bb11bb-cc22-dd33-ee44-55ff55ff55ff Patti Fernandez PattiF@Contoso.com 10/7/2024 12:32:01 AM True MemberList the users who report to a specific user.
Connect-Entra -Scopes 'User.Read','User.Read.All' Get-EntraUserDirectReport -UserId 'SawyerM@contoso.com' | Select-Object Id, displayName, userPrincipalName, createdDateTime, accountEnabled, userType | Format-Table -AutoSizeThe output shows the user's direct report.
id displayName userPrincipalName createdDateTime accountEnabled userType -- ----------- ----------------- --------------- -------------- -------- bbbbbbbb-1111-2222-3333-cccccccccccc Christie Cline ChristieC@Contoso.com 10/7/2024 12:32:25 AM True Member aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb Isaiah Langer IsaiahL@Contoso.com 10/7/2024 12:33:16 AM True MemberAssign a manager to a user.
Connect-Entra -Scopes 'User.ReadWrite.All' Set-EntraUserManager -UserId 'SawyerM@contoso.com' -ManagerId 'AdeleV@contoso.com'-UserId- specifies the ID (as a UserPrincipalName or User ObjectId) of a user in Microsoft Entra ID.-ManagerId- specifies the ID as a UserPrincipalName or User ObjectId) of the Microsoft Entra ID object to assign as a manager.
List users without managers
This example lists users without a manager, helping to identify orphaned accounts, service accounts, or misconfigured profiles for cleanup.
Connect-Entra -Scopes 'User.Read.All'
$allUsers = Get-EntraUser -All
$usersWithoutManagers = foreach ($user in $allUsers) {
$manager = Get-EntraUserManager -UserId $user.Id -ErrorAction SilentlyContinue
if (-not $manager) {
[PSCustomObject]@{
Id = $user.Id
DisplayName = $user.DisplayName
UserPrincipalName = $user.UserPrincipalName
UserType = $user.userType
AccountEnabled = $user.accountEnabled
CreatedDateTime = $user.createdDateTime
}
}
}
$usersWithoutManagers | Format-Table Id, DisplayName, UserPrincipalName, CreatedDateTime, UserType, AccountEnabled -AutoSize
The output lists users without managers.
Id DisplayName UserPrincipalName CreatedDateTime UserType AccountEnabled
-- ----------- ----------------- --------------- -------- --------------
cccccccc-2222-3333-4444-dddddddddddd New User NewUser@tenant.com 10/7/2024 2:24:26 PM Member True
bbbbbbbb-1111-2222-3333-cccccccccccc Sawyer Miller SawyerM@contoso.com 10/7/2024 12:33:36 AM Member True
List disabled users
The following example generates a list of disabled accounts.
Connect-Entra -Scopes 'User.ReadWrite.All'
Get-EntraUser -Filter "accountEnabled eq false" | Select-Object DisplayName, Id, Mail, UserPrincipalName
The output lists disabled users.
DisplayName Id Mail userPrincipalName
----------- -- ---- -----------------
Sawyer Miller hhhhhhhh-7777-8888-9999-iiiiiiiiiiii SawyerM@contoso.com
Kez Michael eeeeeeee-4444-5555-6666-ffffffffffff KezM@contoso.com
Manage deleted users
List recently deleted users.
Connect-Entra -Scopes 'User.ReadWrite.All' Get-EntraDeletedUser -All | Select-Object Id, UserPrincipalName, DisplayName, AccountEnabled, DeletedDateTime, DeletionAgeInDays, UserType | Format-Table -AutoSizeThe output lists deleted users.
Id UserPrincipalName DisplayName AccountEnabled DeletedDateTime DeletionAgeInDays UserType -- ----------------- ----------- -------------- --------------- ----------------- -------- dddddddd-3333-4444-5555-eeeeeeeeeeee {id}AveryS@contoso.com Avery Smith False 2/12/2025 1:15:34 PM 3 MemberRetrieve deleted users sorted by deletion date.
Connect-Entra -Scopes 'User.ReadWrite.All' Get-EntraDeletedUser -All | Sort-Object -Property deletedDateTime -Descending
Upload or retrieve a photo for the user
Upload a photo for a user.
Connect-Entra -Scopes 'User.ReadWrite.All' Set-EntraUserThumbnailPhoto -UserId 'SawyerM@contoso.com' -FilePath 'D:\UserThumbnailPhoto.jpg'This example sets the thumbnail photo of the user specified with the UserId parameter to the image specified with the FilePath parameter.
Retrieve a user’s photo.
Connect-Entra -Scopes 'ProfilePhoto.Read.All' Get-EntraUserThumbnailPhoto -UserId 'SawyerM@contoso.com'This example demonstrates how to retrieve the thumbnail photo of a user that is specified through the value of the
UserIdparameter.
Grant users administrative roles in your organization
The following example shows how to grant a user an administrative role.
Connect-Entra -Scopes 'User.ReadWrite.All', 'RoleManagement.ReadWrite.Directory'
$directoryRole = Get-EntraDirectoryRole -Filter "DisplayName eq 'Helpdesk Administrator'"
$user = Get-EntraUser -Filter "UserPrincipalName eq 'SawyerM@contoso.com'"
Add-EntraDirectoryRoleMember -DirectoryRoleId $directoryRole.Id -MemberId $user.Id
This command adds a user to a Microsoft Entra role. To retrieve roles, use the command Get-EntraDirectoryRole.
-DirectoryRoleId- specifies the unique identifier (ObjectId) of the directory role to which you want to add a member.-MemberId- specifies the unique identifier (ObjectId) of the user, group, or service principal that you want to add as a member of the specified directory role.
Off-board a user
Invalidate active sessions and tokens.
Connect-Entra -Scopes 'Directory.AccessAsUser.All' Revoke-EntraUserAllRefreshToken -UserId 'SawyerM@contoso.com'Revoking authentication tokens invalidates them, thus preventing reaccess through cached logins or remembered sessions.
Disable a user.
Connect-Entra -Scopes 'User.ReadWrite.All' Set-EntraUser -UserId 'SawyerM@contoso.com' -AccountEnabled $falseDisabling the account instantly blocks the user from accessing company resources, applications, and data.
Reset a user's password.
Connect-Entra -Scopes 'Directory.AccessAsUser.All' $securePassword = ConvertTo-SecureString 'Some-strong-random-password' -AsPlainText -Force Set-EntraUserPassword -ObjectId 'SawyerM@contoso.com' -Password $securePasswordResetting the user's password ensures they can't use their old credentials to access company resources before their account is disabled or deleted. This process prevents unauthorized access and potential misuse of the account.
Remove device ownership.
Connect-Entra -Scopes 'Directory.AccessAsUser.All' $device = Get-EntraDevice -Filter "DisplayName eq 'Sawyer Laptop'" $owner = Get-EntraDeviceRegisteredOwner -DeviceId $device.Id Remove-EntraDeviceRegisteredOwner -DeviceId $device.Id -OwnerId $owner.IdRemoving device ownership during offboarding prevents unauthorized access and ensures security compliance.
Disable a user's device.
Connect-Entra -Scopes 'Directory.AccessAsUser.All', 'Device.ReadWrite.All' $device = Get-EntraDevice -Filter "DisplayName eq 'Woodgrove Desktop'" Set-EntraDevice -DeviceObjectId $device.ObjectId -AccountEnabled $falseDisabling a user's device helps safeguard the organization's security, data, and resources.
Remove a user account.
Connect-Entra -Scopes 'Directory.AccessAsUser.All' Remove-EntraUser -UserId 'SawyerM@contoso.com'Note
You can reclaim the user's assigned software and service licenses. See Manage User License for details.