使用OAuth调用Azure DevOps REST API时遇HTTP 203问题排查

问题背景 #

我有一个Entra ID应用，已为其配置Azure DevOps资源的user_impersonation API权限，通过授权码流程可成功获取令牌，但调用Azure DevOps构建更新API（https://dev.azure.com/<organization>/<project>/_apis/build/builds?api-version=7.1-preview.7）时，持续返回HTTP 203状态码。

当前获取令牌的流程如下：

1. 获取授权码：

GET https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/authorize?
client_id=<appId>&
response_type=code&
redirect_uri=https://jwt.ms&
response_mode=query&
scope=499b84ac-1321-427f-aa17-267ca6975798/.default

2. 获取令牌：

POST https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token
client_id=<clientId>&
grant_type=authorization_code&
code=<code>&
redirect_uri=https%3A%2F%2Fjwt.ms&
client_secret=<secret>&
scope=offline_access%20499b84ac-1321-427f-aa17-267ca6975798%2F.default

令牌关键字段：

{
  "aud": "499b84ac-1321-427f-aa17-267ca6975798",
  "iss": "https://sts.windows.net/<tenantId>/",
  "iat": 1705408896,
  "nbf": 1705408896,
  "exp": 1705413139,
  "acr": "1",
  "amr": [
    "pwd",
    "mfa"
  ],
  "appid": "<app Id>",
  "appidacr": "1",
  "email": "<email>",
  "idp": "live.com",
  "scp": "user_impersonation",
  "ver": "1.0"
}

可能原因及修复步骤 #

1. 权限范围不足 #

当前请求令牌使用的499b84ac-1321-427f-aa17-267ca6975798/.default范围仅包含应用注册的静态权限，但Azure DevOps构建更新操作需要更具体的权限，仅user_impersonation无法覆盖该操作。

修复：

• 登录Entra ID应用注册页面，为Azure DevOps资源添加Build.ReadWrite.All（或对应操作的权限）；
• 更新授权码和令牌请求的scope，明确指定所需权限：

  scope=offline_access 499b84ac-1321-427f-aa17-267ca6975798/user_impersonation 499b84ac-1321-427f-aa17-267ca6975798/Build.ReadWrite.All
  

2. 令牌受众格式不匹配 #

Azure DevOps API部分场景要求使用完整资源URI作为受众，而非资源ID。当前令牌的aud字段为资源ID，可能导致验证失败。

修复：

• 将请求scope中的资源ID替换为https://dev.azure.com/，重新获取令牌：
  授权码请求：

  GET https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/authorize?
  client_id=<appId>&
  response_type=code&
  redirect_uri=https://jwt.ms&
  response_mode=query&
  scope=https://dev.azure.com/user_impersonation https://dev.azure.com/Build.ReadWrite.All offline_access
  

  令牌请求：

  POST https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token
  client_id=<clientId>&
  grant_type=authorization_code&
  code=<code>&
  redirect_uri=https%3A%2F%2Fjwt.ms&
  client_secret=<secret>&
  scope=https://dev.azure.com/user_impersonation https://dev.azure.com/Build.ReadWrite.All offline_access
  

3. 用户实际权限缺失 #

即使应用配置了API权限，令牌对应的用户（email字段用户）可能在Azure DevOps组织/项目中没有实际操作权限（如修改构建的权限）。

修复：

• 登录Azure DevOps门户，检查该用户在目标项目中的权限，确保其拥有“编辑构建定义”或对应操作的权限。

4. 令牌版本兼容问题 #

当前令牌版本为ver:1.0，Azure DevOps API更适配v2.0格式令牌。

修复：

• 确保使用OAuth 2.0 v2.0端点请求令牌（当前已使用），同时按v2格式指定scope（如上述步骤中的完整URI形式）。

备选方案 #

若上述方法均无效，使用PAT（个人访问令牌）是Azure DevOps API调用的可靠替代方案。PAT可精细控制权限，配置简单，可先用于验证API操作是否正常。

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