Gerir utilizadores com o Microsoft Entra PowerShell

Os utilizadores são a representação de uma conta profissional ou escolar no Microsoft Entra ou de uma conta Microsoft pessoal no Microsoft Entra ID. O recurso de utilizador no Microsoft Entra PowerShell é a representação de um utilizador, incluindo relações e recursos relevantes para o utilizador.

O recurso do utilizador oferece uma forma direta de aceder e manipular recursos do utilizador sem ter de fazer chamadas extra, consultar informações específicas de autenticação e emitir consultas diretamente contra outros objetos PowerShell do Microsoft Entra.

Pré-requisitos

Para gerir utilizadores com o Microsoft Entra PowerShell, precisa de:

Pode aceder à informação de um utilizador e gerir os seus dados em seu nome ou como uma aplicação com identidade própria.

Integrar um utilizador

Para integrar um utilizador, cria uma nova conta de utilizador no Microsoft Entra ID. Este processo envolve a criação do perfil do utilizador, incluindo o seu nome de visualização, endereço de email e palavra-passe.

Criar um utilizador

Este exemplo cria um novo utilizador.

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

A saída mostra detalhes do utilizador recém-criado.

DisplayName    Id                                     Mail    UserPrincipalName
-----------    --                                     ----    -----------------
New User       aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb           NewUser@contoso.com

Criar utilizadores em massa

Para criar múltiplos utilizadores em massa, pode usar um ficheiro CSV. O ficheiro CSV deve conter os atributos necessários do utilizador, como DisplayName, UserPrincipalName, e PasswordProfile.

# Connect to Microsoft Entra PowerShell
Connect-Entra -Scopes 'User.ReadWrite.All'

# Create a new Password Profile for the new users. We'll be using the same password for all new users in this example
$PasswordProfile = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordProfile
$PasswordProfile.Password = '<Your-Password>'

# Import the csv file. You will need to specify the path and file name of the CSV file in this cmdlet
$NewUsers = import-csv -Path '<path-to-your-csv-file>'

# Loop through all new users in the file to create them in Microsoft Entra ID
ForEach ($user in $NewUsers) {
    # Create a new user in Microsoft Entra ID
    New-EntraUser -UserPrincipalName $user.'EmailAddress' -DisplayName $user.'DisplayName' -GivenName $user.'FirstName' -Surname $user.'LastName' -Department $user.'Department' -MailNickname $user.'MailNickname' -AccountEnabled $true -PasswordProfile $passwordProfile
    }
Primeiro nome Apelido DisplayName Endereço de e-mail Departamento MailNickName
Adele Vance Adele Vance adelev@contoso.com Marketing adelev

A saída apresenta detalhes dos utilizadores recém-criados.

DisplayName Id                                   Mail UserPrincipalName
----------- --                                   ---- -----------------
Adele Vance aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb      adelev@contoso.com

Atualizar a palavra-passe de um utilizador

  1. Para atualizar a palavra-passe de um utilizador por administrador, use este comando:

    Connect-Entra -Scopes 'Directory.AccessAsUser.All'
$newPassword = '<strong-password>'
$securePassword = ConvertTo-SecureString $newPassword -AsPlainText -Force
Set-EntraUserPasswordProfile -UserId 'SawyerM@contoso.com' -Password $securePassword

  2. Para atualizar a palavra-passe do utilizador com sessão iniciada (autosserviço), use este comando:

    Connect-Entra -Scopes 'Directory.AccessAsUser.All'
$currentPassword = ConvertTo-SecureString '<strong-password>' -AsPlainText -Force
$newPassword = ConvertTo-SecureString '<strong-password>' -AsPlainText -Force
Set-EntraSignedInUserPassword -CurrentPassword $currentPassword -NewPassword $newPassword

    Este comando permite aos utilizadores alterar as suas próprias palavras-passe sem privilégios de administrador.

Carregar ou recuperar uma fotografia para o utilizador

  1. Carrega uma foto para um utilizador.

    Connect-Entra -Scopes 'User.ReadWrite.All'
Set-EntraUserThumbnailPhoto -UserId 'SawyerM@contoso.com' -FilePath 'D:\UserThumbnailPhoto.jpg'

    Este exemplo define a fotografia em miniatura do utilizador especificada com o parâmetro UserId para a imagem especificada com o parâmetro FilePath.

  2. Obtenha a fotografia de um utilizador.

    Connect-Entra -Scopes 'ProfilePhoto.Read.All'
Get-EntraUserThumbnailPhoto -UserId 'SawyerM@contoso.com'

    Este exemplo demonstra como recuperar a fotografia em miniatura de um utilizador especificada através do valor do UserId parâmetro.

Conceda aos utilizadores funções administrativas na sua organização

Conceder aos utilizadores funções administrativas na sua organização permite-lhes realizar tarefas específicas e gerir recursos. Pode atribuir aos utilizadores funções como Administrador de Grupo, Administrador de Utilizadores ou outros papéis personalizados.

Para aprender a atribuir funções a utilizadores usando o Microsoft Entra PowerShell, consulte Atribuir funções aos utilizadores.

Pesquisar utilizadores

Pode procurar utilizadores na sua organização com base em vários atributos, como displayName, mailNickname, userPrincipalName, department e jobTitle. O exemplo seguinte mostra como pesquisar um utilizador por userPrincipalName

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "userPrincipalName eq 'SawyerM@contoso.com'"

O resultado mostra os dados do utilizador com base numa userPrincipalName pesquisa.

DisplayName      Id                                   Mail                 UserPrincipalName     
-----------      --                                   ----                 -----------------     
Sawyer Miller   aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb SawyerM@contoso.com  SawyerM@contoso.com

Auditar os utilizadores por determinados critérios

Pode auditar os utilizadores com base em determinados critérios, como a atividade de início de sessão e a pertença a grupos. Esta funcionalidade ajuda-o a acompanhar a atividade dos utilizadores e a gerir o seu acesso aos recursos.

Recuperar a atividade de início de sessão de um utilizador

O exemplo seguinte mostra como recuperar a atividade de início de sessão de um utilizador específico.

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'

O resultado mostra a atividade de início de sessão do utilizador.

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

Descarregue todas as atividades de início de sessão dos utilizadores

O exemplo seguinte recupera todas as contas de utilizador licenciadas e a sua última atividade de início de sessão bem-sucedida. Exporta os dados para um ficheiro CSV para análise posterior.

# Connect to Microsoft Entra PowerShell  

Connect-Entra -Scopes 'User.Read.All','AuditLog.Read.All','Directory.Read.All'

try {
     Get-EntraUser -All -Property Id, UserPrincipalName, DisplayName, SignInActivity -ErrorAction Stop |
         Select-Object `
             Id, `
             UserPrincipalName, `
             DisplayName, `
             @{ Name = 'LastSignInDateTime';           Expression = { $_.SignInActivity.LastSignInDateTime } }, `
             @{ Name = 'LastSuccessfulSignInDateTime'; Expression = { $_.SignInActivity.LastSuccessfulSignInDateTime } } |
         Export-Csv -Path 'C:\temp\lastSignIns.csv' -NoTypeInformation -Encoding UTF8 -ErrorAction Stop

     Write-Host "Sign-in activity exported successfully to lastSignIns.csv"
 }
 catch {
     Write-Error "Failed to retrieve or export data: $_"
 }

Este exemplo recupera tanto a última data de início de sessão como a última data bem-sucedida de todos os utilizadores da sua organização. Os dados são então exportados para um ficheiro CSV nomeado lastSignIns.csv no C:\temp diretório.

Listar as pertenças de grupos de um utilizador

O exemplo seguinte lista os grupos a que um utilizador pertence.

Connect-Entra -Scopes 'User.Read'
Get-EntraUserMembership -UserId 'SawyerM@contoso.com' |
 Select-Object Id, displayName, createdDateTime, '@odata.type' |
 Format-Table -AutoSize

A saída mostra as afiliações do utilizador.

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 estes comandos para listar as entidades a que um utilizador pertence:

Arranja um gestor de utilizador, subordinados diretos e atribui um gestor a um utilizador

  1. Arranja um gestor de utilizadores.

    Connect-Entra -Scopes 'User.Read.All'
Get-EntraUserManager -UserId 'SawyerM@contoso.com' |
    Select-Object Id, displayName, userPrincipalName, createdDateTime, accountEnabled, userType |
    Format-Table -AutoSize

    A saída mostra o gestor do utilizador.

    id                                    displayName     userPrincipalName                    createdDateTime           accountEnabled  userType
--                                    -----------     -----------------                    ---------------           --------------  --------
11bb11bb-cc22-dd33-ee44-55ff55ff55ff  Patti Fernandez PattiF@Contoso.com                 10/7/2024 12:32:01 AM      True           Member

  2. Liste os utilizadores que reportam a um utilizador específico.

    Connect-Entra -Scopes 'User.Read','User.Read.All'
Get-EntraUserDirectReport -UserId 'SawyerM@contoso.com' |
    Select-Object Id, displayName, userPrincipalName, createdDateTime, accountEnabled, userType |
    Format-Table -AutoSize

    A saída mostra o subordinado direto do utilizador.

    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           Member

  3. Atribua um gestor a um utilizador.

    Connect-Entra -Scopes 'User.ReadWrite.All'
Set-EntraUserManager -UserId 'SawyerM@contoso.com' -ManagerId 'AdeleV@contoso.com'
    • -UserId- especifica o ID (como UserPrincipalName ou User ObjectId) de um utilizador no Microsoft Entra ID.
    • -ManagerId- especifica o ID como UserPrincipalName ou User ObjectId) do objeto Microsoft Entra ID para atribuir como gestor.

Listar utilizadores sem gestores

Este exemplo lista utilizadores sem gestor, ajudando a identificar contas órfãs, contas de serviço ou perfis mal configurados para limpeza.

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

A saída lista utilizadores sem gestores.

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

Listar utilizadores com deficiência

O exemplo seguinte gera uma lista de contas desativadas.

Connect-Entra -Scopes 'User.ReadWrite.All'
Get-EntraUser -Filter "accountEnabled eq false" | Select-Object DisplayName, Id, Mail, UserPrincipalName

O resultado apresenta utilizadores desativados.

DisplayName    Id                                   Mail userPrincipalName
-----------    --                                   ---- -----------------
Sawyer Miller  hhhhhhhh-7777-8888-9999-iiiiiiiiiiii      SawyerM@contoso.com
Kez Michael    eeeeeeee-4444-5555-6666-ffffffffffff      KezM@contoso.com

Conteúdo relacionado

  • Last updated on