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

Description

指令Get-EntraUser小程式會接收來自 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：依識別碼取得使用者

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）或使用者 ID。

範例 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 會取得所有與 SearchString 值與 DisplayName 或 UserPrincipalName 首字母相符的使用者。

範例 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：每用戶多重身份驗證報告

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

在這個範例中，我們會擷取所有以 Ada 開頭的 MailNick 使用者。

範例 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 建議將全球管理員角色分配至少於五人以達成最佳實務。 請參閱最佳做法。

範例 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

僅回傳服務配置錯誤中包含授權相關問題的使用者，這些問題顯示需要進行授權對帳（例如授權不足、相依性違規、互斥方案）。 指令本內部則匹配常見的授權錯誤模式以縮小結果集範圍。

參數屬性

類型: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
別名:選取

參數集

(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
別名:極限

參數集

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。