Get-EntraUser

模块:
Microsoft.Entra.Users Module v1.3

获取用户。

语法

GetQuery (默认值) 

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

说明

该 Get-EntraUser cmdlet 从Microsoft Entra ID获取用户。

示例

示例 1：获取前三个用户

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

此示例演示如何从Microsoft Entra ID获取前三名用户。 您可以将 -Limit 用作 -Top 的别名。

示例 2：按 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

此命令获取指定的用户。

  • -UserId 将 ID 指定为用户主体名称（UPN）或 UserId。

示例 3：在检索的用户之间进行搜索

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

此 cmdlet 获取与 DisplayName 或 UserPrincipalName 中的第一个字符匹配 SearchString 值的所有用户。

示例 4：检索用户的密码策略

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

此示例演示如何获取用户的密码策略。 若要更新它，请运行 Get-EntraUser -UserId SawyerM@contoso.com | Set-EntraUser -PasswordPolicies DisablePasswordExpiration。

示例 5：每用户 MFA 报告

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

此示例显示每用户 MFA 状态的报告。

注意：Microsoft建议使用条件访问策略和安全默认值来管理多重身份验证（MFA），而不是依赖旧版每用户 MFA。

示例 6：按 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

此命令获取指定的用户。

示例 7：通过 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

在此示例中，我们将检索 MailNickname 以 Ada 开头的所有用户。

示例 8：获取用户的 SignInActivity

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

此示例演示如何通过选择属性来检索特定用户的 SignInActivity。

示例 9：列出具有已禁用帐户的用户

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

此示例演示如何检索具有禁用帐户的所有用户。

示例 10：列出基于特定国家/地区的用户

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

此示例演示如何检索位于加拿大的所有用户。

示例 11：列出每个部门的用户计数

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

此示例演示如何检索每个部门中的用户计数。

示例 12：列出具有活动许可证的已禁用用户

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

此示例演示如何检索具有活动许可证的已禁用用户。

示例 13：检索具有活动许可证的来宾用户

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

此示例演示如何检索具有活动许可证的来宾用户。

示例 14：列出具有特定许可证的用户

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

此示例演示如何检索具有特定许可证的用户。

示例 15：检索没有经理的用户

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

此示例演示如何检索没有经理的用户。

示例 16：列出所有来宾用户

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

此示例演示如何检索所有来宾用户的列表。

示例 17：列出最近创建的五个用户

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

此示例演示如何检索最近创建的用户。

示例 18：具有全局管理员角色的用户列表

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

此示例演示如何列出具有特定角色的所有用户，例如 Global Administrator。 Microsoft建议将全局管理员角色分配给少于 5 个人，以便最佳做法。 请参阅最佳做法。

示例 19：列出过去 30 天内撤消会话的所有用户

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

此示例演示如何列出过去 30 天内撤消的会话的所有用户。

参数

-All

列出所有页面。

参数属性

类型:System.Management.Automation.SwitchParameter
默认值:False
支持通配符:False
不显示:False

参数集

(All)
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-EnabledFilter

根据用户帐户的状态筛选用户。 有效值为 EnabledOnly 和 DisabledOnly。 指定后，该 cmdlet 会将 accountEnabled 约束添加到任何现有 -Filter 表达式。

参数属性

类型:System.String
默认值:None
支持通配符:False
不显示:False
别名:没有

参数集

GetFiltered
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-Filter

指定 OData v4.0 筛选器语句。 此参数控制返回的对象。 有关使用 OData 进行查询的详细信息，可 在此处找到。

参数属性

类型:System.String
默认值:None
支持通配符:False
不显示:False

参数集

GetQuery
Position:Named
必需:False
来自管道的值:True
来自管道的值（按属性名称）:True
来自剩余参数的值:False

-HasErrorsOnly

仅返回一个或多个服务预配或验证错误（通过 serviceProvisioningErrors 集合显示）的用户。 使用此开关快速识别需要管理修正的标识。

参数属性

类型:System.Management.Automation.SwitchParameter
默认值:False
支持通配符:False
不显示:False
别名:没有

参数集

GetFiltered
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-LicenseReconciliationNeededOnly

仅返回服务预配错误包括许可证相关问题的用户，指示需要许可证对帐（例如许可证不足、依赖项冲突、互斥计划）。 在内部，cmdlet 匹配常见的许可证错误模式以缩小结果集的范围。

参数属性

类型:System.Management.Automation.SwitchParameter
默认值:False
支持通配符:False
不显示:False
别名:没有

参数集

GetFiltered
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-PageSize

指定 -PageSize 时，该命令可能会进行多个网络调用来检索区块（页面）中的数据，直到达到 -Top 或 -All 定义的限制，具体取决于所使用的限制。

参数属性

类型:System.Int32
默认值:None
支持通配符:False
不显示:False

参数集

(All)
Position:Named
必需:False
来自管道的值:True
来自管道的值（按属性名称）:True
来自剩余参数的值:False

-Property

指定要返回的属性。

参数属性

类型:

System.String[]

默认值:None
支持通配符:False
不显示:False
别名:Select

参数集

(All)
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-SearchString

指定搜索字符串。

参数属性

类型:System.String
默认值:None
支持通配符:False
不显示:False

参数集

GetVague
Position:Named
必需:False
来自管道的值:True
来自管道的值（按属性名称）:True
来自剩余参数的值:False

-Synchronized

仅返回从本地 Active Directory同步的用户（那些用户）。onPremisesSyncEnabled eq true 这对于区分仅限云的标识与混合托管标识非常有用。

参数属性

类型:System.Management.Automation.SwitchParameter
默认值:False
支持通配符:False
不显示:False
别名:没有

参数集

GetFiltered
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-Top

指定要返回的最大记录数。

参数属性

类型:System.Int32
默认值:None
支持通配符:False
不显示:False
别名:Limit

参数集

GetQuery
Position:Named
必需:False
来自管道的值:True
来自管道的值（按属性名称）:True
来自剩余参数的值:False

-UnlicensedUsersOnly

仅返回没有分配许可证的用户（assignedLicenses 计数等于 0）。 这有助于识别可能尚未具有所需服务访问权限的用户。

参数属性

类型:System.Management.Automation.SwitchParameter
默认值:False
支持通配符:False
不显示:False
别名:没有

参数集

GetFiltered
Position:Named
必需:False
来自管道的值:False
来自管道的值（按属性名称）:False
来自剩余参数的值:False

-UserId

在Microsoft Entra ID中指定用户的 ID（作为用户主体名称（UPN）或 UserId。

参数属性

类型:System.String
默认值:None
支持通配符:False
不显示:False
别名:对象标识符 (ObjectId), UPN, Identity, UserPrincipalName

参数集

GetById
Position:Named
必需:True
来自管道的值:True
来自管道的值（按属性名称）:True
来自剩余参数的值:False

CommonParameters

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。