Get-EntraUser

Obtém um usuário.

Sintaxe

GetQuery (Predefinição)

Get-EntraUser

    [-Filter <String>]
    [-All]
    [-Top <Int32>]
    [-PageSize <Int32>]
    [-Property <String[]>]
    [<CommonParameters>]

GetByValue

Get-EntraUser

    [-SearchString <String>]
    [-All]
    [-Property <String[]>]
    [<CommonParameters>]

GetById

Get-EntraUser

    -UserId <String>
    [-All]
    [-Property <String[]>]
    [<CommonParameters>]

GetFiltered

Get-EntraUser

    [-All]
    [-Top <Int32>]
    [-PageSize <Int32>]
    [-EnabledFilter <String>]
    [-HasErrorsOnly]
    [-LicenseReconciliationNeededOnly]
    [-Synchronized]
    [-UnlicensedUsersOnly]
    [-Property <String[]>]
    [<CommonParameters>]

Descrição

O Get-EntraUser cmdlet recebe um utilizador do Microsoft Entra ID.

Exemplos

Exemplo 1: Obtenha os três melhores utilizadores

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Top 3
DisplayName      Id                                   Mail                  UserPrincipalName
-----------      --                                   ----                  -----------------
Angel Brown      cccccccc-2222-3333-4444-dddddddddddd AngelB@contoso.com    AngelB@contoso.com
Avery Smith      dddddddd-3333-4444-5555-eeeeeeeeeeee AveryS@contoso.com    AveryS@contoso.com
Sawyer Miller    eeeeeeee-4444-5555-6666-ffffffffffff SawyerM@contoso.com   SawyerM@contoso.com

Este exemplo demonstra como obter os três primeiros utilizadores do Microsoft Entra ID. Você pode usar -Limit como um alias para -Top.

Exemplo 2: Obter um utilizador por ID

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com'
DisplayName Id                                   Mail                                 UserPrincipalName
----------- --                                   ----                                 -----------------
Sawyer Miller bbbbbbbb-1111-2222-3333-cccccccccccc sawyerm@tenant.com sawyerm@tenant.com

Este comando recebe o utilizador especificado.

  • -UserId Especifica o ID como nome principal de utilizador (UPN) ou UserId.

Exemplo 3: Pesquisa entre utilizadores recuperados

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -SearchString 'New'
DisplayName        Id                                   Mail UserPrincipalName
-----------        --                                   ---- -----------------
New User88         bbbbbbbb-1111-2222-3333-cccccccccccc      demo99@tenant.com
New User           cccccccc-2222-3333-4444-dddddddddddd      NewUser@tenant.com

Este cmdlet reúne todos os utilizadores que comparam o valor de SearchString com os primeiros caracteres em DisplayName ou UserPrincipalName.

Exemplo 4: Política de recuperação da palavra-passe do utilizador

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -UserId 'SawyerM@contoso.com' `
              -Property UserPrincipalName, PasswordPolicies |
    Select-Object UserPrincipalName,
                  @{
                      Name = "PasswordNeverExpires"
                      Expression = { $_.PasswordPolicies -contains "DisablePasswordExpiration" }
                  }
userPrincipalName            PasswordNeverExpires
-----------------            --------------------
SawyerM@contoso.com                 True

Este exemplo mostra como obter a política de palavra-passe de um utilizador. Para atualizar, execute Get-EntraUser -UserId SawyerM@contoso.com | Set-EntraUser -PasswordPolicies DisablePasswordExpiration.

Exemplo 5: Relatório MFA por utilizador

Connect-Entra -scope 'User.Read.All', 'UserAuthenticationMethod.Read.All'
$users = Get-EntraUser -All -Select Id, UserPrincipalName, DisplayName
Write-Output "Amount of requests within `"fetchAll`": $($users.Count)"
$usersReport = [System.Collections.ArrayList]::new()
$users | ForEach-Object {

    $userProperties = @{
        Id                = $_.Id
        DisplayName       = $_.DisplayName
        UserPrincipalName = $_.UserPrincipalName
        PerUserMFAState   = (Get-EntraBetaUserAuthenticationRequirement -UserId $_.Id).PerUserMFAState
    }

    [void]$usersReport.Add([PSCustomObject]$userProperties)
}

$usersReport | Format-Table -AutoSize
UserPrincipalName       DisplayName       PerUserMFAState Id
-----------------       -----------       --------------- --
AngelB@contoso.com      Angel Brown       enforced        cccccccc-2222-3333-4444-dddddddddddd
AveryS@contoso.com      Avery Smith       disabled        dddddddd-3333-4444-5555-eeeeeeeeeeee
SawyerM@contoso.com     Sawyer Miller     enforced        eeeeeeee-4444-5555-6666-ffffffffffff
ChristieC@contoso.com   Christie Cline    enabled         bbbbbbbb-1111-2222-3333-cccccccccccc
PattiF@contoso.com      Patti Fernandez   disabled        aaaaaaaa-bbbb-cccc-1111-222222222222

Este exemplo mostra um relatório do estado MFA por utilizador.

Nota: A Microsoft recomenda o uso de políticas de Acesso Condicional e predefinidos de segurança para gerir a autenticação multifator (MFA) em vez de depender do MFA legado por utilizador.

Exemplo 6: Obter um utilizador pelo userPrincipalName

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "userPrincipalName eq 'SawyerM@contoso.com'"
DisplayName Id                                   Mail UserPrincipalName
----------- --                                   ---- -----------------
Sawyer Miller    cccccccc-2222-3333-4444-dddddddddddd      SawyerM@contoso.com

Este comando recebe o utilizador especificado.

Exemplo 7: Obter um utilizador pelo MailNickname

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "startsWith(MailNickname,'Ada')"
DisplayName     Id                                   Mail                                UserPrincipalName
-----------     --                                   ----                                -----------------
Mark Adams bbbbbbbb-1111-2222-3333-cccccccccccc Adams@contoso.com Adams@contoso.com

Neste exemplo, recuperamos todos os utilizadores cujo MailNickname começa com Ada.

Exemplo 8: Obter LogInActivity de um utilizador

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'
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

Este exemplo demonstra como recuperar a LogInActivity de um utilizador específico selecionando uma propriedade.

Exemplo 9: Listar utilizadores com contas desativadas

Connect-Entra -Scopes 'User.Read.All'
Get-EntraUser -Filter "accountEnabled eq false" | Select-Object DisplayName, Id, Mail, UserPrincipalName
DisplayName        Id                                   Mail UserPrincipalName
-----------        --                                   ---- -----------------
New User           cccccccc-2222-3333-4444-dddddddddddd      NewUser@tenant.com

Este exemplo demonstra como recuperar todos os utilizadores com contas desativadas.

Exemplo 10: Listar utilizadores baseados num país específico

Connect-Entra -Scopes 'User.Read.All'
$usersInCanada = Get-EntraUser -Filter "Country eq 'Canada'"
$usersInCanada | Select-Object Id, DisplayName, UserPrincipalName, OfficeLocation, Country | Format-Table -AutoSize
Id                                   DisplayName   UserPrincipalName         OfficeLocation   Country
--                                   -----------   -----------------         --------------   -------
cccccccc-2222-3333-4444-dddddddddddd  New User     NewUser@tenant.com        23/2102          Canada

Este exemplo demonstra como recuperar todos os utilizadores sediados no Canadá.

Exemplo 11: Liste a contagem de utilizadores por departamento

Connect-Entra -Scopes 'User.Read.All'
$departmentCounts = Get-EntraUser -All | Group-Object -Property Department | Select-Object Name, @{Name="MemberCount"; Expression={$_.Count}}
$departmentCounts | Format-Table Name, MemberCount -AutoSize
Name                 MemberCount
----                 -----------
                               7
Engineering                    2
Executive Management           1
Finance                        1
HR                             1

Este exemplo demonstra como recuperar o número de utilizadores em cada departamento.

Exemplo 12: Listar utilizadores desativados com licenças ativas

Connect-Entra -Scopes 'User.Read.All'
$disabledUsersWithLicenses = Get-EntraUser -Filter "accountEnabled eq false" -All | Where-Object {
    $_.AssignedLicenses -ne $null -and $_.AssignedLicenses.Count -gt 0
}
$disabledUsersWithLicenses | Select-Object Id, DisplayName, UserPrincipalName, AccountEnabled | Format-Table -AutoSize
Id                                   DisplayName  UserPrincipalName           AccountEnabled
--                                   -----------  -----------------           --------------
cccccccc-2222-3333-4444-dddddddddddd  New User     NewUser@tenant.com          False

Este exemplo demonstra como recuperar utilizadores com deficiência com licenças ativas.

Exemplo 13: Recuperar utilizadores convidados com licenças ativas

Connect-Entra -Scopes 'User.Read.All'
$guestUsers = Get-EntraUser -Filter "userType eq 'Guest'" -All
$guestUsersWithLicenses = foreach ($guest in $guestUsers) {
    if ($guest.AssignedLicenses.Count -gt 0) {
        [PSCustomObject]@{
            Id                = $guest.Id
            DisplayName       = $guest.DisplayName
            UserPrincipalName = $guest.UserPrincipalName
            AssignedLicenses  = ($guest.AssignedLicenses | ForEach-Object { $_.SkuId }) -join ", "
        }
    }
}
$guestUsersWithLicenses | Format-Table Id, DisplayName, UserPrincipalName, AssignedLicenses -AutoSize
Id                                   DisplayName  UserPrincipalName                                  AssignedLicenses
--                                   -----------  -----------------                                  ----------------
cccccccc-2222-3333-4444-dddddddddddd Sawyer Miller sawyerm_gmail.com#EXT#@contoso.com c42b9cae-ea4f-4ab7-9717-81576235ccac

Este exemplo demonstra como recuperar utilizadores convidados com licenças ativas.

Exemplo 14: Listar utilizadores com uma licença específica

Connect-Entra -Scopes 'User.Read.All'
$skuId = (Get-EntraSubscribedSku | Where-Object { $_.SkuPartNumber -eq 'POWERAPPS_DEV' }).SkuId
Get-EntraUser -Filter "assignedLicenses/any(l:l/skuId eq $skuId)" -Select id, displayName, userPrincipalName, userType, accountEnabled, assignedLicenses |
Select-Object id, displayName, userPrincipalName, userType, accountEnabled | Format-Table -AutoSize
id                                   displayName     userPrincipalName        userType accountEnabled
--                                   -----------     -----------------        -------- --------------
cccccccc-2222-3333-4444-dddddddddddd Angel Brown     AngelB@contoso.com       Member   True
dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith     AveryS@contoso.com       Member   True

Este exemplo demonstra como recuperar utilizadores com uma licença específica.

Exemplo 15: Recuperar utilizadores sem gestores

Connect-Entra -Scopes 'User.Read.All'
$allUsers = Get-EntraUser -All
$usersWithoutManagers = foreach ($user in $allUsers) {
    $manager = Get-EntraUserManager -ObjectId $user.Id -ErrorAction SilentlyContinue
    if (-not $manager) {
        [PSCustomObject]@{
            Id                = $user.Id
            DisplayName       = $user.DisplayName
            UserPrincipalName = $user.UserPrincipalName
        }
    }
}
$usersWithoutManagers | Format-Table Id, DisplayName, UserPrincipalName -AutoSize
Id                                   DisplayName     UserPrincipalName
--                                   -----------     -----------------
cccccccc-2222-3333-4444-dddddddddddd  New User       NewUser@tenant.com
bbbbbbbb-1111-2222-3333-cccccccccccc  Sawyer Miller  SawyerM@contoso.com

Este exemplo demonstra como recuperar utilizadores sem gestores.

Exemplo 16: Liste todos os utilizadores convidados

Connect-Entra -Scopes 'User.Read.All'
$guestUsers = Get-EntraUser -Filter "userType eq 'Guest'" -All
$guestUsers | Select-Object DisplayName, UserPrincipalName, Id, createdDateTime, creationType, accountEnabled, UserState | Format-Table -AutoSize
DisplayName     UserPrincipalName                                 Id                                   CreatedDateTime       CreationType   AccountEnabled  UserState
-----------     -----------------                                 --                                   ---------------       ------------   --------------  ---------
Sawyer Miller   sawyerm_gmail.com#EXT#@contoso.com                bbbbbbbb-1111-2222-3333-cccccccccccc 9/13/2024 6:37:33 PM  Invitation     True            Accepted

Este exemplo demonstra como recuperar a lista de todos os utilizadores convidados.

Exemplo 17: Lista cinco utilizadores recentemente criados

Get-EntraUser -All | Sort-Object -Property createdDateTime -Descending | Select-Object -First 5
DisplayName       Id                                   Mail                  UserPrincipalName
-----------       --                                   ----                  -----------------
Angel Brown       cccccccc-2222-3333-4444-dddddddddddd  AngelB@contoso.com    AngelB@contoso.com
Avery Smith       dddddddd-3333-4444-5555-eeeeeeeeeeee  AveryS@contoso.com    AveryS@contoso.com
Sawyer Miller     eeeeeeee-4444-5555-6666-ffffffffffff  SawyerM@contoso.com   SawyerM@contoso.com
Christie Cline    bbbbbbbb-1111-2222-3333-cccccccccccc  ChristieC@contoso.com ChristieC@contoso.com
Patti Fernandez   aaaaaaaa-bbbb-cccc-1111-222222222222  PattiF@contoso.com    PattiF@contoso.com

Este exemplo mostra como recuperar os utilizadores recentemente criados.

Exemplo 18: Lista de utilizadores com função de Administrador Global

Connect-Entra -Scopes 'User.Read.All', 'RoleManagement.Read.Directory'
$roleId = Get-EntraDirectoryRoleTemplate | Where-Object { $_.DisplayName -eq 'Global Administrator' } | Select-Object -ExpandProperty Id
$globalAdmins = Get-EntraDirectoryRoleAssignment -Filter "roleDefinitionId eq '$roleId'" | ForEach-Object {
    Get-EntraUser -UserId $_.PrincipalId
}
$globalAdmins | Select-Object Id, DisplayName, UserPrincipalName, CreatedDateTime, AccountEnabled | Format-Table -AutoSize
id                                   displayName   userPrincipalName        createdDateTime          accountEnabled
--                                   -----------   -----------------        ---------------          --------------
cccccccc-2222-3333-4444-dddddddddddd Angel Brown   AngelB@contoso.com       3/7/2024 12:34:59 AM     True
dddddddd-3333-4444-5555-eeeeeeeeeeee Avery Smith   AveryS@contoso.com       10/1/2024 9:47:06 AM     True

Este exemplo mostra como listar todos os utilizadores com um papel específico, como Global Administrator. A Microsoft recomenda atribuir o cargo de Administrador Global a menos de cinco pessoas para as melhores práticas. Consulte as melhores práticas.

Exemplo 19: Liste todos os utilizadores com sessões revogadas nos últimos 30 dias

Connect-Entra -Scopes 'User.Read.All'
$pastDate = (Get-Date).AddDays(-30).ToUniversalTime()
Get-EntraUser | Where-Object { $_.signInSessionsValidFromDateTime -ge $pastDate } |
Select-Object DisplayName, UserPrincipalName, signInSessionsValidFromDateTime
displayName     userPrincipalName      signInSessionsValidFromDateTime
-----------     -----------------      -------------------------------
Angel Brown     AngelB@contoso.com     03/03/2025 16:13:47
Avery Smith     AveryS@contoso.com     03/03/2025 16:05:02

Este exemplo mostra como listar todos os utilizadores com sessões revogadas nos últimos 30 dias.

Parâmetros

-All

Liste todas as páginas.

Propriedades dos parâmetros

Tipo:System.Management.Automation.SwitchParameter
Valor predefinido:False
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-EnabledFilter

Filtra os utilizadores com base no estado das suas contas. Os valores válidos são EnabledOnly e DisabledOnly. Quando especificado, o cmdlet adiciona uma accountEnabled restrição a qualquer expressão existente -Filter .

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:None

Conjuntos de parâmetros

GetFiltered
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Filter

Especifica uma instrução de filtro OData v4.0. Este parâmetro controla quais os objetos que são devolvidos. Detalhes sobre consultas com OData podem ser encontrados aqui.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

GetQuery
Posto:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos:False

-HasErrorsOnly

Devolve apenas utilizadores que apresentam um ou mais erros de provisionamento ou validação de serviços (manifestados através da serviceProvisioningErrors coleção). Use esta mudança para identificar rapidamente identidades que necessitam de remediação administrativa.

Propriedades dos parâmetros

Tipo:System.Management.Automation.SwitchParameter
Valor predefinido:False
Suporta carateres universais:False
NãoMostrar:False
Aliases:None

Conjuntos de parâmetros

GetFiltered
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-LicenseReconciliationNeededOnly

Devolve apenas utilizadores cujos erros de provisionamento de serviços incluem questões relacionadas com licenças que indicam que a reconciliação de licenças é necessária (por exemplo, licenças insuficientes, violações de dependência, planos mutuamente exclusivos). Internamente, o cmdlet corresponde a padrões comuns de erro de licença para restringir o conjunto de resultados.

Propriedades dos parâmetros

Tipo:System.Management.Automation.SwitchParameter
Valor predefinido:False
Suporta carateres universais:False
NãoMostrar:False
Aliases:None

Conjuntos de parâmetros

GetFiltered
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-PageSize

Quando -PageSize é especificado, o comando pode fazer múltiplas chamadas de rede para recuperar dados em blocos (páginas), continuando até atingir o limite definido por -Top ou -All, dependendo do que for utilizado.

Propriedades dos parâmetros

Tipo:System.Int32
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos:False

-Property

Especifica propriedades a devolver.

Propriedades dos parâmetros

Tipo:

System.String[]

Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Select

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-SearchString

Especifica uma cadeia de pesquisa.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

GetVague
Posto:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos:False

-Synchronized

Retorna apenas utilizadores sincronizados do Active Directory no local (aqueles com onPremisesSyncEnabled eq true). Isto é útil para distinguir identidades exclusivas da cloud de identidades geridas híbridas.

Propriedades dos parâmetros

Tipo:System.Management.Automation.SwitchParameter
Valor predefinido:False
Suporta carateres universais:False
NãoMostrar:False
Aliases:None

Conjuntos de parâmetros

GetFiltered
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-Top

Especifica o número máximo de registos a devolver.

Propriedades dos parâmetros

Tipo:System.Int32
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:Limit

Conjuntos de parâmetros

GetQuery
Posto:Named
Obrigatório:False
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos:False

-UnlicensedUsersOnly

Devolve apenas utilizadores que não têm licenças atribuídas (assignedLicenses contagem é igual a 0). Isto ajuda a identificar utilizadores que podem ainda não ter acesso ao serviço necessário.

Propriedades dos parâmetros

Tipo:System.Management.Automation.SwitchParameter
Valor predefinido:False
Suporta carateres universais:False
NãoMostrar:False
Aliases:None

Conjuntos de parâmetros

GetFiltered
Posto:Named
Obrigatório:False
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-UserId

Especifica o ID (como Nome Principal de Utilizador (UPN) ou UserId) de um utilizador no Microsoft Entra ID.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:IdentificadorDoObjeto, UPN, Identidade, Nome Principal do Utilizador

Conjuntos de parâmetros

GetById
Posto:Named
Obrigatório:True
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.