基于REST API获取Azure DevOps(TFS)用户安全组的PowerShell脚本

以下脚本支持传入用户邮箱/用户名作为入参，自动调用REST API拉取指定用户所属的全部安全组（包含嵌套组继承的成员关系），云版Azure DevOps、本地部署TFS均兼容。

前置要求 #

• 执行账号持有目标Azure DevOps组织/TFS集合的安全读取权限
• 提前准备个人访问令牌（PAT），令牌需开通Identity (Read)、Security (Read)、Project and Team (Read)权限范围

完整脚本 #

param(
    [Parameter(Mandatory=$true)]
    [string]$OrganizationUrl,
    [Parameter(Mandatory=$true)]
    [string]$UserIdentifier,
    [Parameter(Mandatory=$true)]
    [string]$Pat
)

# 构造鉴权请求头
$base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$($Pat)"))
$headers = @{
    Authorization = "Basic $base64AuthInfo"
    "Content-Type" = "application/json"
}

# 匹配目标用户，获取用户身份描述符
$searchUserApi = "$OrganizationUrl/_apis/identities?searchFilter=General&filterValue=$([Uri]::EscapeDataString($UserIdentifier))&queryMembership=None&api-version=7.1-preview.1"
try {
    $userResp = Invoke-RestMethod -Uri $searchUserApi -Method Get -Headers $headers -ErrorAction Stop
}
catch {
    Write-Error "用户查询失败：$($_.Exception.Message)"
    exit 1
}

if (-not $userResp.value -or $userResp.value.Count -eq 0) {
    Write-Error "未找到与标识 $UserIdentifier 匹配的用户，请核对输入"
    exit 1
}
$targetUser = $userResp.value[0]
Write-Host "匹配到目标用户：$($targetUser.providerDisplayName)，关联账号：$($targetUser.properties.Account.'$value')" -ForegroundColor Green

# 查询用户所有所属组（含嵌套组向上追溯）
$membershipApi = "$OrganizationUrl/_apis/identities/$($targetUser.descriptor)/memberships?direction=Up&api-version=7.1-preview.1"
try {
    $membershipResp = Invoke-RestMethod -Uri $membershipApi -Method Get -Headers $headers -ErrorAction Stop
}
catch {
    Write-Error "组成员关系查询失败：$($_.Exception.Message)"
    exit 1
}

# 拉取组详情并格式化输出
$result = @()
foreach ($member in $membershipResp.value) {
    $groupApi = "$OrganizationUrl/_apis/identities/$($member.containerDescriptor)?api-version=7.1-preview.1"
    $groupInfo = Invoke-RestMethod -Uri $groupApi -Method Get -Headers $headers
    $result += [PSCustomObject]@{
        组名称 = $groupInfo.providerDisplayName
        组描述 = if ($groupInfo.description) { $groupInfo.description } else { "无描述" }
        所属范围 = if ($groupInfo.properties.ScopeName) { $groupInfo.properties.ScopeName.'$value' } else { "组织全局" }
        类别 = if ($groupInfo.isTeam) { "项目团队" } else { "安全组" }
    }
}

Write-Host "`n共查询到用户所属组/团队 $($result.Count) 个：" -ForegroundColor Cyan
$result | Format-Table -AutoSize
return $result

使用方法 #

• 云版Azure DevOps调用示例：

  .\Get-UserAdGroups.ps1 -OrganizationUrl "https://dev.azure.com/你的组织名称" -UserIdentifier "user@yourcorp.com" -Pat "你生成的PAT令牌"
  

• 本地TFS调用示例：

  .\Get-UserAdGroups.ps1 -OrganizationUrl "http://你的TFS服务地址/tfs/目标集合名称" -UserIdentifier "域\用户名" -Pat "你生成的PAT令牌"
  

注意：如果搜索用户时出现重名匹配错误，可自行修改脚本中用户匹配逻辑，增加工号、域账号等精确匹配规则即可。

内容的提问来源于stack exchange，提问作者noamsh88