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 按以下顺序解析凭据。第一个产生凭据的来源胜出。

在 ant CLI 中，Claude Models on Google Cloud (Anthropic managed) 的设置优先级低于联合身份（federation）环境变量，高于活动配置文件（profile）。这些设置包括项目、工作区 ID 和位置。您可以通过 --google-cloud-* 标志或 ANTHROPIC_GOOGLE_CLOUD_* 变量来设置它们。只要设置了其中任意一项，CLI 就会使用这些设置。使用这些设置时，CLI 会从 Google Application Default Credentials（应用默认凭据）获取凭据。

加载配置文件时，环境变量会填充配置文件省略的字段，但绝不会覆盖配置文件显式设置的字段。例如，仅当活动配置文件未设置 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 遵循相同的解析顺序，因此在此处配置的联合配置文件无需额外设置即可为这些工具进行身份验证。

文件布局

配置文件和凭据文件都带有一个 major.minor 格式的顶层字符串 version 字段（当前为 "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 的服务账户为目标。有效权限是规则范围与服务账户角色的交集。

验证规则

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

有关完整的参数详情和响应架构，请参阅服务账户 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 将交换失败报告为 WorkloadIdentityError，其中包含 HTTP 状态以及响应体中的错误详情。在 Python、TypeScript 和 Ruby 中，请求 ID 位于错误对象上；在 Java 中，位于异常的响应头中。在 Go 中，它仅出现在错误消息中，因为错误类型位于内部包中；C# 和 PHP 的错误不携带请求 ID。

无论哪项检查失败，每次断言拒绝都会返回相同的不透明 401 authentication_error，消息固定为 Authentication failed；可区分的错误会让调用方能够探测规则配置。拒绝原因记录在 Claude Console 中身份验证历史记录的该次尝试条目上，例如当 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 自定义授权服务器），请确认您的轮换策略会在首次使用之前发布新密钥。