Manage users with Microsoft Entra PowerShell
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.
Manage users in your organization
To manage users, you can perform the following common user management tasks:
Create users
The following example creates a new user using the UserPrincipalName parameter.
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
DisplayName Id Mail UserPrincipalName
----------- -- ---- -----------------
New User aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb NewUser@contoso.com
Retrieve a user's sign-in activity
The following example shows how to retrieves the sign-in activity of a specific user.
Connect-Entra -Scopes 'User.Read.All','AuditLog.Read.All'
Get-EntraUser -ObjectId 'SawyerM@contoso.com' -Property 'SignInActivity' | Select-Object -ExpandProperty 'SignInActivity'
lastSignInDateTime : 07/09/2024 09:15:41
lastNonInteractiveSignInDateTime : 07/09/2024 07:15:41
lastSuccessfulSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastNonInteractiveSignInRequestId : 00001111-aaaa-2222-bbbb-3333cccc4444
lastSignInRequestId : bbbbbbbb-1111-2222-3333-aaaaaaaaaaaa
lastSuccessfulSignInDateTime : 07/09/2024 09:15:41
List a user's group memberships
- List a user’s group memberships.
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserMembership -ObjectId 'SawyerM@contoso.com'
Id DeletedDateTime
-- ---------------
eeeeeeee-4444-5555-6666-ffffffffffff
ffffffff-5555-6666-7777-gggggggggggg
gggggggg-6666-7777-8888-hhhhhhhhhhhh
hhhhhhhh-7777-8888-9999-iiiiiiiiiiii
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 -ObjectId 'SawyerM@contoso.com'
Id DeletedDateTime
-- ---------------
eeeeeeee-4444-5555-6666-ffffffffffff
- List the users who report to a specific user.
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserDirectReport -ObjectId 'SawyerM@contoso.com'
Id DeletedDateTime
-- ---------------
eeeeeeee-4444-5555-6666-ffffffffffff
- Assign a manager to a user.
Connect-Entra -Scopes 'User.ReadWrite.All'
$manager = Get-EntraUser -Filter "UserPrincipalName eq 'AdeleV@contoso.com'"
$params = @{
ObjectId = 'SawyerM@contoso.com'
RefObjectId = $manager.ObjectId
}
Set-EntraUserManager @params
-ObjectId- specifies the ID (as a UserPrincipalName or ObjectId) of a user in Microsoft Entra ID.-RefObjectId- specifies the ID as a UserPrincipalName or ObjectId) of the Microsoft Entra ID object to assign as a manager.
List inactive 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
DisplayName Id Mail userPrincipalName
----------- -- ---- -----------------
Sawyer Miller hhhhhhhh-7777-8888-9999-iiiiiiiiiiii SawyerM@contoso.com
Kez Michael eeeeeeee-4444-5555-6666-ffffffffffff KezM@contoso.com
Upload or retrieve a photo for the user
- Upload a photo for a user.
Connect-Entra -Scopes 'User.ReadWrite.All'
$photoParams = @{
ObjectId = 'SawyerM@contoso.com'
FilePath = 'D:\UserThumbnailPhoto.jpg'
}
Set-EntraUserThumbnailPhoto @photoParams
This example sets the thumbnail photo of the user specified with the ObjectId parameter to the image specified with the FilePath parameter.
- Retrieve a user’s photo.
Connect-Entra -Scopes 'ProfilePhoto.Read.All'
Get-EntraUserThumbnailPhoto -ObjectId 'SawyerM@contoso.com'
This example demonstrates how to retrieve the thumbnail photo of a user that is specified through the value of the ObjectId parameter.
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'"
$roleMemberParams = @{
ObjectId = $directoryRole.ObjectId
RefObjectId = $user.ObjectId
}
Add-EntraDirectoryRoleMember @roleMemberParams
This command adds a user to a Microsoft Entra role. To retrieve roles, use the command Get-EntraDirectoryRole.
-ObjectId- specifies the unique identifier (ObjectId) of the directory role to which you want to add a member.-RefObjectId- 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.
Manage user licenses
- Get details of a user's licenses.
Connect-Entra -Scopes 'User.ReadWrite.All'
Get-EntraUserLicenseDetail -ObjectId 'SawyerM@contoso.com'
Id SkuId SkuPartNumber
-- ----- -------------
ouL7hgqFM0GkdqXrzahI4u7E6wa1G91HgSARMkvFTgY 06ebc4ee-1bb5-47dd-8120-11324bc54e06 SPE_E5
- Assign a license to a user based on a template user.
Connect-Entra -Scopes 'User.ReadWrite.All', 'Organization.Read.All'
$User = Get-EntraUser -ObjectId 'SawyerM@contoso.com'
$License = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicense
$License.SkuId = (Get-EntraSubscribedSku | Where SkuPartNumber -eq 'FLOW_FREE').SkuId
$Licenses = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicenses
$Licenses.AddLicenses = $License
Set-EntraUserLicense -ObjectId $User.ObjectId -AssignedLicenses $Licenses
The following example shows how to assign a FLOW_FREE license to a user with ObjectId SawyerM@contoso.com.
- Remove a license from a user.
Connect-Entra -Scopes 'User.ReadWrite.All', 'Organization.Read.All'
$UserPrincipalName = 'SawyerM@contoso.com'
$User = Get-EntraUser -ObjectId $UserPrincipalName
$SkuId = (Get-EntraUserLicenseDetail -ObjectId $UserPrincipalName).SkuId
$Licenses = New-Object -TypeName Microsoft.Open.AzureAD.Model.AssignedLicenses
$Licenses.RemoveLicenses = $SkuId
Set-EntraUserLicense -ObjectId $User.ObjectId -AssignedLicenses $Licenses
Name Value
---- -----
preferredLanguage
givenName
@odata.context https://graph.microsoft.com/v1.0/$metadata#users/$entity
id hhhhhhhh-7777-8888-9999-iiiiiiiiiiii
mail SawyerM@contoso.com
userPrincipalName SawyerM@contoso.com
jobTitle
displayName Sawyer Miller
officeLocation
surname
mobilePhone
businessPhones {}
This example shows how to remove a license from a user.
Offboard a user
- Invalidate active sessions and tokens.
Connect-Entra -Scopes 'Directory.AccessAsUser.All'
Revoke-EntraUserAllRefreshToken -ObjectId '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 -ObjectId 'SawyerM@contoso.com' -AccountEnabled $false
Disabling 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 $securePassword
Resetting the user's password ensures they can't use their old credentials to access company resources before their account is disabled or deleted. This prevents unauthorized access and potential misuse of the account.
- Disable a user's device.
Connect-Entra -Scopes 'Directory.AccessAsUser.All'
$Device = Get-EntraDevice -Filter "DisplayName eq 'Sawyer Laptop'"
$Owner = Get-EntraDeviceRegisteredOwner -ObjectId $Device.ObjectId
Remove-EntraDeviceRegisteredOwner -ObjectId $Device.ObjectId -OwnerId $Owner.ObjectId
Disabling 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 -ObjectId 'SawyerM@contoso.com'
Note
You can also reclaim any licenses for software and services that were assigned to the user.