ado-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ado-auth

Authenticate to Azure DevOps (ADO) and diagnose auth failures. This is a verify and troubleshoot skill — the bundled

create-backlog.cs

already implements both auth methods, so you are not writing new auth code here. You are confirming a token works and the org/project point where the user expects, then unblocking the create/query skills ([[ado-create-work-items]], the orchestrator [[findings-to-ado-backlog]]).

ADO accepts two credential styles. Pick A unless the user has a reason to use a PAT.

完成Azure DevOps（ADO）认证并诊断认证失败问题。这是一项验证与故障排查技能——捆绑的

create-backlog.cs

已实现两种认证方式，因此无需在此编写新的认证代码。你需要确认令牌可用，且组织/项目指向用户预期的位置，从而为创建/查询技能（[[ado-create-work-items]]、编排器[[findings-to-ado-backlog]]）扫清障碍。

ADO支持两种凭证类型。除非用户有明确理由使用PAT，否则优先选择方式A。

Method A — Entra token via Azure CLI (recommended)

方式A — 通过Azure CLI获取Entra令牌（推荐）

Why preferred: no long-lived secret to store, and it rides the user's existing

az

session. The resource id below is the global Azure DevOps application id (same for every tenant) — it tells Entra "mint a token for Azure DevOps".

powershell

az login
$token = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv

Use it as a bearer header:

Authorization: Bearer <token>

推荐理由：无需存储长期密钥，且可复用用户现有的

az

会话。下方的资源ID是全局Azure DevOps应用ID（所有租户通用）——它告知Entra“为Azure DevOps生成令牌”。

powershell

az login
$token = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv

将其用作Bearer头部：

Authorization: Bearer <token>

。

Method B — Personal Access Token (PAT)

方式B — 个人访问令牌（PAT）

Use when

az login

isn't available (e.g. a service context) or the user already has a PAT. Scope must include Work Items (Read & Write). ADO PATs go in a Basic header where the username is empty and the password is the PAT:

powershell

$env:AZDO_PAT = "<your-pat>"
$basic = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:AZDO_PAT"))

当无法使用

az login

（例如服务环境）或用户已拥有PAT时使用。权限范围必须包含工作项（读写）。ADO PAT需放入Basic头部，其中用户名为空，密码为PAT：

powershell

$env:AZDO_PAT = "<your-pat>"
$basic = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:AZDO_PAT"))

header -> Authorization: Basic <basic>


`create-backlog.cs` reads `AZDO_PAT` automatically: if it's set it uses Basic auth,
otherwise it shells out to `az` for an Entra token. So setting (or unsetting)
`AZDO_PAT` is how you switch methods for that script — you don't pass a flag.


`create-backlog.cs`会自动读取`AZDO_PAT`：如果已设置则使用Basic认证，否则会调用`az`获取Entra令牌。因此，设置（或取消设置）`AZDO_PAT`是切换该脚本认证方式的方法——无需传递标志。

Verify the credential works

验证凭证是否可用

Run this before kicking off a real create. A

against the project endpoint proves the token is valid and that the user can see the target org/project — the two things most auth failures actually break. Set

AZDO_ORG

to the org name only (not a URL):

powershell

$env:AZDO_ORG     = "Cartagena365"   # the NAME, not https://dev.azure.com/...
$env:AZDO_PROJECT = "GlassHull"
$token = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv
$uri = "https://dev.azure.com/$($env:AZDO_ORG)/_apis/projects/$($env:AZDO_PROJECT)?api-version=7.1"
Invoke-RestMethod -Uri $uri -Headers @{ Authorization = "Bearer $token" }

PAT variant — swap the header for:

@{ Authorization = "Basic $([Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:AZDO_PAT")))" }

returns the project's JSON (id, name, state). Anything else, see below.

For a broader prereq sweep (az, .NET 10, python/openpyxl, env vars) run the bundled checker instead — it's read-only and changes nothing:

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"

在执行实际创建操作前运行此验证。针对项目端点返回

状态码，证明令牌有效且用户可访问目标组织/项目——这是大多数认证失败的两个核心问题。将

AZDO_ORG

设置为组织名称（而非URL）：

powershell

$env:AZDO_ORG     = "Cartagena365"   # 仅填写名称，不要https://dev.azure.com/...
$env:AZDO_PROJECT = "GlassHull"
$token = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv
$uri = "https://dev.azure.com/$($env:AZDO_ORG)/_apis/projects/$($env:AZDO_PROJECT)?api-version=7.1"
Invoke-RestMethod -Uri $uri -Headers @{ Authorization = "Bearer $token" }

PAT变体——将头部替换为：

@{ Authorization = "Basic $([Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$env:AZDO_PAT")))" }

状态码会得到项目的JSON数据（ID、名称、状态）。若出现其他情况，请查看下方内容。

如需更全面的前置检查（az、.NET 10、python/openpyxl、环境变量），请运行捆绑的检查脚本——它是只读的，不会更改任何内容：

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check.ps1"

Troubleshooting

故障排查

Symptom	Cause	Fix
HTTP 401 Unauthorized	No token, or it expired	`az login` , then re-fetch the token (Entra tokens are short-lived — re-run the `get-access-token` line). For PAT: check it hasn't expired/been revoked.
HTTP 403 Forbidden	Token is valid but lacks rights	PAT scope missing Work Items (Read & Write) — reissue with that scope. For Entra: the account lacks board/project permission — get added to the project / area path.
"A potentially dangerous Request.Path value was detected (:)"	`AZDO_ORG` was set to a full URL (e.g. `https://dev.azure.com/Cartagena365` ) instead of the bare org name. The `:` from `https:` lands inside the request path.	Set `AZDO_ORG` to the org name only: `$env:AZDO_ORG = "Cartagena365"` .
200 but wrong / empty results	Token is fine; you're pointed at the wrong place	Check `AZDO_ORG` / `AZDO_PROJECT` — confirm the project name's exact casing, and that this org actually contains it (the verify call's JSON is the source of truth).
"could not start az" / "failed to get Entra token"	Azure CLI not installed or no active login	Install Azure CLI (https://aka.ms/installazurecli), run `az login` , retry. Or fall back to Method B ( `AZDO_PAT` ).

症状	原因	修复方法
HTTP 401 未授权	无令牌或令牌已过期	执行 `az login` ，然后重新获取令牌（Entra令牌有效期较短——重新运行 `get-access-token` 命令）。对于PAT：检查令牌是否过期/被撤销。
HTTP 403 禁止访问	令牌有效但权限不足	PAT权限范围缺少工作项（读写）——重新生成包含该权限的PAT。对于Entra：账户缺少看板/项目权限——请求添加到项目/区域路径。
"A potentially dangerous Request.Path value was detected (:)"	`AZDO_ORG` 被设置为完整URL（例如 `https://dev.azure.com/Cartagena365` ），而非仅组织名称。 `https:` 中的 `:` 会出现在请求路径中。	将 `AZDO_ORG` 设置为仅组织名称： `$env:AZDO_ORG = "Cartagena365"` 。
返回200但结果错误/为空	令牌正常，但指向错误位置	检查 `AZDO_ORG` / `AZDO_PROJECT` ——确认项目名称的大小写完全正确，且该组织确实包含此项目（验证调用返回的JSON是权威依据）。
"could not start az" / "failed to get Entra token"	未安装Azure CLI或无活跃登录	安装Azure CLI（https://aka.ms/installazurecli），执行`az login `，然后重试。或切换至方式B（` AZDO_PAT`）。

Hand-off

交接

Once the verify call returns

, auth is good — continue with [[ado-create-work-items]] (which drives

create-backlog.cs

) or [[ado-writeback-tracking]]. The same

AZDO_ORG

AZDO_PROJECT

env vars carry straight into those steps, so leave them set in this shell. Field shapes and the

org

project

precedence rules live in

references/data-contracts.md

一旦验证调用返回

，说明认证正常——可继续执行[[ado-create-work-items]]（调用

create-backlog.cs

）或[[ado-writeback-tracking]]。相同的

AZDO_ORG

AZDO_PROJECT

环境变量会直接带入后续步骤，因此请在当前shell中保持其设置。字段格式以及

org

project

的优先级规则请查看

references/data-contracts.md

。