Get-EntraUser
Obtém um usuário.
Sintaxe
GetQuery (Default)
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>]
Description
O Get-EntraUser cmdlet obtém um usuário de Microsoft Entra ID.
Exemplos
Exemplo 1: Obter os três principais usuários
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 principais usuários do Microsoft Entra ID. Você pode usar -Limit como um alias para -Top.
Exemplo 2: Obter um usuário 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
Esse comando obtém o usuário especificado.
-
-UserIdEspecifica a ID como um UPN (nome de entidade de usuário) ou UserId.
Exemplo 3: pesquisar entre usuários 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
Esse cmdlet obtém todos os usuários que correspondem ao valor de SearchString com os primeiros caracteres em DisplayName ou UserPrincipalName.
Exemplo 4: recuperar a política de senha do usuário
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 senha de um usuário. Para atualizá-lo, execute Get-EntraUser -UserId SawyerM@contoso.com | Set-EntraUser -PasswordPolicies DisablePasswordExpiration.
Exemplo 5: relatório de MFA por usuário
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 de MFA por usuário.
Observação: Microsoft recomenda usar políticas de Acesso Condicional e padrões de segurança para gerenciar a MFA (autenticação multifator) em vez de depender da MFA herdada por usuário.
Exemplo 6: Obter um usuário por 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
Esse comando obtém o usuário especificado.
Exemplo 7: Obter um usuário 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 usuários cujo MailNickname começa com o Ada.
Exemplo 8: Obter SignInActivity de um usuário
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 o SignInActivity de um usuário específico selecionando uma propriedade.
Exemplo 9: Listar usuários com contas desabilitadas
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 usuários com contas desabilitadas.
Exemplo 10: Listar usuários com base em um 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 usuários com base no Canadá.
Exemplo 11: Listar contagem de usuários 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 a contagem de usuários em cada departamento.
Exemplo 12: Listar usuários desabilitados 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 usuários desabilitados com licenças ativas.
Exemplo 13: recuperar usuários 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 usuários convidados com licenças ativas.
Exemplo 14: Listar usuários 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 usuários com uma licença específica.
Exemplo 15: recuperar usuários sem gerentes
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 usuários sem gerentes.
Exemplo 16: Listar todos os usuários 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 usuários convidados.
Exemplo 17: Listar cinco usuários criados recentemente
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 usuários criados recentemente.
Exemplo 18: Lista de usuários 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 usuários com uma função específica, como Global Administrator. Microsoft recomenda atribuir a função de Administrador Global a menos de cinco pessoas para prática recomendada. Confira as práticas recomendadas.
Exemplo 19: Listar todos os usuários 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 usuários com sessões revogadas nos últimos 30 dias.
Parâmetros
-All
Listar todas as páginas.
Propriedades do parâmetro
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-EnabledFilter
Filtra os usuários com base no estado de suas contas. Os valores válidos são EnabledOnly e DisabledOnly. Quando especificado, o cmdlet adiciona uma restrição accountEnabled a qualquer expressão existente -Filter .
Propriedades do parâmetro
| Tipo: | System.String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Filter
Especifica uma instrução de filtro OData v4.0. Esse parâmetro controla quais objetos são retornados. Detalhes sobre como consultar com o OData podem ser encontrados aqui.
Propriedades do parâmetro
| Tipo: | System.String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
GetQuery
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-HasErrorsOnly
Retorna apenas usuários que têm um ou mais erros de provisionamento ou validação de serviço (exibidos por meio da serviceProvisioningErrors coleção). Use essa opção para identificar rapidamente as identidades que exigem correção administrativa.
Propriedades do parâmetro
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-LicenseReconciliationNeededOnly
Retorna somente usuários cujos erros de provisionamento de serviço incluem problemas relacionados à licença 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 aos padrões comuns de erro de licença para restringir o conjunto de resultados.
Propriedades do parâmetro
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-PageSize
Quando -PageSize for especificado, o comando poderá fazer várias chamadas de rede para recuperar dados em partes (páginas), continuando até atingir o limite definido por -Top ou -All, dependendo de qual é usado.
Propriedades do parâmetro
| Tipo: | System.Int32 |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-Property
Especifica as propriedades a serem retornadas.
Propriedades do parâmetro
| Tipo: | System.String[] |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | Select |
Conjuntos de parâmetros
(All)
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-SearchString
Especifica uma cadeia de caracteres de pesquisa.
Propriedades do parâmetro
| Tipo: | System.String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
Conjuntos de parâmetros
GetVague
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-Synchronized
Retorna apenas usuários sincronizados de Active Directory local (aqueles comonPremisesSyncEnabled eq true). Isso é útil para distinguir identidades somente na nuvem de identidades gerenciadas híbridas.
Propriedades do parâmetro
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-Top
Especifica o número máximo de registros a serem retornados.
Propriedades do parâmetro
| Tipo: | System.Int32 |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | Limit |
Conjuntos de parâmetros
GetQuery
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | False |
-UnlicensedUsersOnly
Retorna apenas usuários que não têm licenças atribuídas (assignedLicenses contagem igual a 0). Isso ajuda a identificar usuários que ainda não têm o acesso ao serviço necessário.
Propriedades do parâmetro
| Tipo: | System.Management.Automation.SwitchParameter |
| Valor padrão: | False |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | None |
Conjuntos de parâmetros
GetFiltered
| Cargo: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline pelo nome da propriedade: | False |
| Valor dos argumentos restantes: | False |
-UserId
Especifica a ID (como um UPN (Nome de Entidade de Usuário) ou UserId) de um usuário no Microsoft Entra ID.
Propriedades do parâmetro
| Tipo: | System.String |
| Valor padrão: | None |
| Dá suporte a curingas: | False |
| DontShow: | False |
| Aliases: | IdentificadorDeObjeto, UPN, Identidade, Nome Principal do Usuário |
Conjuntos de parâmetros
GetById
| Cargo: | Named |
| Obrigatório: | True |
| Valor do pipeline: | True |
| Valor do pipeline pelo nome da propriedade: | True |
| Valor dos argumentos restantes: | 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.