Edit

Share via

Manage users with Microsoft Entra PowerShell

  • Article

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:

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 = '[email protected]'
    AccountEnabled = $true
    MailNickName = 'NewUser'
}
New-EntraUser @userParams

DisplayName    Id                                   Mail UserPrincipalName
-----------    --                                   ---- -----------------
New User aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb      [email protected]

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 '[email protected]' -Property 'SignInActivity' | Select-Object -Property Id, DisplayName, UserPrincipalName -ExpandProperty 'SignInActivity'

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                 : [email protected]

List a user's group memberships

  1. List a user’s group memberships.
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserMembership -UserId '[email protected]'

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

  1. Get a user's manager.
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserManager -UserId '[email protected]'

    Id                                   DeletedDateTime
--                                   ---------------
eeeeeeee-4444-5555-6666-ffffffffffff
  1. List the users who report to a specific user.
Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserDirectReport -UserId '[email protected]'

    Id                                   DeletedDateTime
--                                   ---------------
eeeeeeee-4444-5555-6666-ffffffffffff
  1. Assign a manager to a user.
Connect-Entra -Scopes 'User.ReadWrite.All'
$manager = Get-EntraUser -Filter "UserPrincipalName eq '[email protected]'"
Set-EntraUserManager -UserId '[email protected]' -RefObjectId $manager.Id
  • -UserId - specifies the ID (as a UserPrincipalName or User ObjectId) of a user in Microsoft Entra ID.
  • -RefObjectId - specifies the ID as a UserPrincipalName or User ObjectId) of the Microsoft Entra ID object to assign as a manager.

List inactive users

  1. 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      [email protected]
Kez Michael   eeeeeeee-4444-5555-6666-ffffffffffff      [email protected]

Upload or retrieve a photo for the user

  1. Upload a photo for a user.
Connect-Entra -Scopes 'User.ReadWrite.All'
Set-EntraUserThumbnailPhoto -UserId '[email protected]' -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.

  1. Retrieve a user’s photo.
Connect-Entra -Scopes 'ProfilePhoto.Read.All'
Get-EntraUserThumbnailPhoto -UserId '[email protected]'

This example demonstrates how to retrieve the thumbnail photo of a user that is specified through the value of the UserId 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 '[email protected]'"
Add-EntraDirectoryRoleMember -DirectoryRoleId $directoryRole.Id -RefObjectId $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.
  • -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.

Off-board a user

  1. Invalidate active sessions and tokens.
Connect-Entra -Scopes 'Directory.AccessAsUser.All'
Revoke-EntraUserAllRefreshToken -UserId '[email protected]'

Revoking authentication tokens invalidates them, thus preventing reaccess through cached logins or remembered sessions.

  1. Disable a user.
Connect-Entra -Scopes 'User.ReadWrite.All'
Set-EntraUser -UserId '[email protected]' -AccountEnabled $false

Disabling the account instantly blocks the user from accessing company resources, applications, and data.

  1. Reset a user's password.
Connect-Entra -Scopes 'Directory.AccessAsUser.All'
$securePassword = ConvertTo-SecureString 'Some-strong-random-password' -AsPlainText -Force
Set-EntraUserPassword -ObjectId '[email protected]' -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 process prevents unauthorized access and potential misuse of the account.

  1. Disable a user's device.
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.Id

Disabling a user's device helps safeguard the organization's security, data, and resources.

  1. Remove a user account.
Connect-Entra -Scopes 'Directory.AccessAsUser.All'
Remove-EntraUser -UserId '[email protected]'

Note

You can also reclaim any licenses for software and services that were assigned to the user.

Next steps