WIF 参考

本页汇总了 Workload Identity Federation（工作负载身份联合）的配置界面、验证约束和错误映射。有关设置演练，请参阅提供商指南。

令牌交换请求

POST /v1/oauth/token 接受使用 RFC 7523 jwt-bearer 授权类型的 JSON 请求体。SDK 会根据环境变量为您构建此请求；每个提供商指南中的 cURL 示例展示了原始请求体。

令牌交换响应

POST /v1/oauth/token 返回标准的 OAuth 2.0 令牌响应（RFC 6749 §5.1）：

环境变量

SDK 读取这些变量，以便在无需构造函数参数的情况下执行联合令牌交换。

仅当 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID 以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 之一全部设置时，直接环境变量联合路径才会激活。ANTHROPIC_WORKSPACE_ID 会一并读取，但不影响激活条件。

凭据优先级

SDK 按以下顺序解析凭据。第一个产生凭据的来源胜出。

加载配置文件时，环境变量会填充配置文件省略的任何字段，但绝不会覆盖配置文件显式设置的字段。例如，仅当活动配置文件未设置 workspace_id 时，ANTHROPIC_WORKSPACE_ID 才会填充该字段。

配置文件配置

"Profile"（配置文件）是 SDK 和 ant CLI 都会读取的命名配置文件。配置文件让您可以将联合参数随容器镜像一起发布，或在不更改代码的情况下在不同环境之间切换。

配置目录

SDK 按以下顺序定位配置目录：

1. $ANTHROPIC_CONFIG_DIR
2. Linux 和 macOS 上的 ~/.config/anthropic
3. Windows 上的 %APPDATA%\Anthropic

活动配置文件

活动配置文件名称按以下顺序解析：

1. $ANTHROPIC_PROFILE
2. <config_dir>/active_config 的内容（由 ant profile activate <name> 写入的单行文件）
3. 字面名称 default

Claude Code 和 Claude Agent SDK 遵循相同的解析顺序，因此在此处配置的联合配置文件也可以为这些工具进行身份验证，无需额外设置。

文件布局

配置文件和凭据文件都带有一个顶层字符串 version 字段，格式为 major.minor（当前为 "1.0"）。SDK 会自动写入此字段，以便未来版本能够检测并迁移旧格式；手动编写配置时可省略它，SDK 会将该文件视为当前版本。

联合配置文件示例

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

如果省略 authentication.identity_token，SDK 会回退到环境中的 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN。

OAuth 作用域

您在联合规则上设置的 oauth_scope 决定了所签发的访问令牌可以调用哪些 Claude API 端点。

对令牌作用域之外的端点发出的请求会返回 HTTP 403。目前不提供更细粒度的作用域（按资源，或读与写）。

权限边界

联合规则的 oauth_scope 是一个上限：所签发的令牌永远不能超过它。目标服务账户的 organization_role（developer 或 admin）决定了哪些作用域可被授予，因此授予 org:admin 的规则必须以 organization_role=admin 的服务账户为目标。有效权限是规则作用域与服务账户角色的交集。

验证规则

当您创建或更新签发者和规则时，以及在交换时验证传入的 JWT 时，Anthropic 会强制执行这些约束。

有关完整的参数详情和响应模式，请参阅服务账户 API 参考、联合签发者 API 参考和联合规则 API 参考。

资源字段

URL 字段

issuer_url、jwks.discovery_base 和 jwks.url 字段会经过验证：

URL 验证失败会返回 400 invalid_request_error，错误消息以字段名作为前缀（例如 issuer_url: url must use https scheme）。

JWT 验证

规则匹配语义

联合规则的 match 块决定是否接受传入的 JWT。所有已填充的字段以 AND 语义进行评估：JWT 必须满足每个已填充的匹配器。subject_prefix、claims 或 condition 中至少必须设置一个；仅包含 audience（或完全没有匹配器）的 match 块会被拒绝。这可以防止出现会接受来自某个签发者的所有令牌的规则。

CEL 求值环境

condition 表达式可以访问单个变量：

示例：

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

错误

令牌交换错误

POST /v1/oauth/token 以标准的 API 错误格式返回错误。SDK 将交换失败包装在类型化的 FederationExchangeError（或对应语言的等价类型）中，该类型公开 HTTP 状态、响应体和 request_id。

无论哪项检查失败，每次断言拒绝都会返回相同的不透明 401 authentication_error，并带有固定消息 Authentication failed；可区分的错误会让调用方得以探测规则配置。拒绝原因记录在身份验证历史中该次尝试的条目上，例如当 sub 声明未通过规则的 subject_prefix 时为 match_subject_prefix，或当规则跨越多个工作区而请求未指定任何工作区时为 workspace_id_required。在规则所属组织得到确认之前被拒绝的请求（上述 400 invalid_request_error 系列）不会留下历史条目；其响应消息会直接指明问题。没有匹配历史条目的 401 通常意味着 federation_rule_id 本身未被识别。

常见的 SDK 端故障

排查失败的交换

401 authentication_error 响应是有意设计为不透明的，其消息始终为 Authentication failed；拒绝原因记录在身份验证历史中，而不在响应中。

一种常见的不透明故障是重放的断言：携带 jti 声明的断言只能交换一次，因此重新发送相同 JWT 的工作负载（重试循环，或重新读取未轮换令牌的刷新）会在第二次交换时被拒绝。身份验证历史页面会以原因 jti_reused 显示这些尝试；解决方法是为每次交换签发新的断言。

如果您仍需要从 JWT 本身进行调试，请按顺序完成以下检查：

1. 1

   解码 JWT

   解码您发送的断言，以便将每个声明与您的签发者和规则配置进行比较：

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   检查 iss 是否与签发者匹配

   解码后的 iss 声明必须与注册的 issuer_url 逐字节相等，包括协议、端口和任何末尾斜杠。单个字符不匹配即会导致验证失败。

3. 3

   检查 aud 是否与规则匹配

   解码后的 aud 声明必须以精确匹配的方式包含规则的 audience 值。当 aud 是数组时，必须有一个元素精确匹配。

4. 4

   检查 sub 和每个 claims 条目

   将 sub 与规则的 subject_prefix 进行比较（区分大小写；末尾的 * 表示前缀匹配，其他情况为精确匹配）。将规则 claims 映射中的每个键与同名的顶层声明进行比较。

5. 5

   检查 exp、nbf 和 iat

   exp 必须在未来，nbf/iat 必须在过去，且在 30 秒偏差窗口内。如果工作负载主机的时钟发生漂移，原本有效的令牌也会被拒绝。

6. 6

   检查 JWKS 可达性

   对于 discovery 模式，通过端口 443 上的公共 HTTPS 获取 <jwks.discovery_base or issuer_url>/.well-known/openid-configuration，并确认 jwks_uri 可解析。对于 explicit_url，直接获取 JWKS URL。对于 inline，确认自您注册密钥以来签发者的签名密钥未发生轮换。

   如果签发者轮换了签名密钥并立即开始使用它签名，在 Anthropic 的 JWKS 缓存刷新期间，交换可能会失败长达一分钟。请参阅密钥轮换与缓存。

JWKS 来源模式

当您注册联合签发者时，jwks 字段控制 Anthropic 如何获取用于验证来自该签发者的 JWT 签名的公钥。它是一个以 type 为键的可辨识联合：

可辨识联合在结构上使配套字段互斥。discovery 和 explicit_url 还都接受一个可选的 ca_cert_pem 字符串，用于从私有 CA 提供 TLS 的签发者。

密钥轮换与缓存

在 discovery 和 explicit_url 模式下，Anthropic 会缓存获取到的 JWKS。如果您的身份提供商发布了新的签名密钥并立即开始使用它签名令牌，则在缓存刷新期间，提交这些令牌的交换可能会因签名错误而失败长达 1 分钟。

为避免此窗口期，请在您的身份提供商开始使用新签名密钥签名令牌之前至少 15 分钟将其发布到 JWKS 中，并将被取代的密钥保留在 JWKS 中，直到其签名的令牌过期。托管身份提供商通常会自行遵循此规范。如果您运营自己的签发者（自管理 Kubernetes 集群、SPIRE OIDC 发现提供商，或配置了轮换周期的 Okta 自定义授权服务器），请确认您的轮换策略会在首次使用之前发布新密钥。