工作负载身份联合

"Workload Identity Federation"（工作负载身份联合），即 WIF，允许您的工作负载使用短期的 "OpenID Connect"（OIDC）令牌而非长期的 sk-ant-... API 密钥向 Claude API 进行身份验证。这些令牌来自您已在运营的身份提供商（IdP）：AWS IAM、Google Cloud，或任何符合标准的 OIDC 颁发者，例如 GitHub Actions、Kubernetes、SPIFFE、Microsoft Entra ID 或 Okta。

您的工作负载出示一个由您的身份提供商签名的 JWT。Anthropic 根据您在 Claude Console 中配置的信任规则对其进行验证，然后返回一个绑定到您组织中某个服务账号的短期 Anthropic 访问令牌。无需生成、存储在 CI 中、轮换或担心泄露任何静态密钥。

工作负载身份联合通过将静态 API 密钥替换为在几分钟内过期（而非永不过期）的令牌来增强您的安全态势。但它本身并不是完整的安全方案：联合身份验证的安全性取决于签署 JWT 的上游身份提供商。请将工作负载身份联合与您的 IdP 已支持的控制措施（工作负载身份绑定、条件访问、审计日志）结合使用，以实现纵深防御。



概念

在任何工作负载可以进行联合之前，您需要在 Claude Console 中配置三种资源。它们共同表达了"由颁发者 X 签名、声明符合 Y 特征的令牌，可以作为服务账号 Z 执行操作"。



服务账号

服务账号（svac_...）是您的 Anthropic 组织内的一个具名的非人类身份。它是联合令牌所代表的主体。服务账号存在于组织级别，当您将其添加为某个工作区的成员时，它便在该工作区中生效。在令牌交换时，Anthropic 会检查联合规则的工作区是否与服务账号的工作区成员资格之一匹配；随后生成的令牌将遵循该工作区的速率限制和用量归属，与 API 密钥相同。与人类用户不同，服务账号没有电子邮件、没有密码，也无法登录 Console。每个服务账号都隐式地是您组织默认工作区的成员；对于它需要在其中执行操作的任何其他工作区，请显式添加成员资格。

与 API 密钥的关键区别在于：API 密钥本身就是凭据，而服务账号是按需为其生成凭据。您可以审计哪些工作负载以哪个服务账号的身份执行了操作。



联合颁发者

联合颁发者（fdis_...）将一个 OIDC 身份提供商注册到您的组织。注册颁发者即告知 Anthropic："由此提供商签名的 JWT 可以为我的组织声明工作负载身份。"

颁发者有两项配置：

• **颁发者 URL：**出现在提供商 JWT 中的确切 iss 声明值，例如 https://token.actions.githubusercontent.com 或 https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE。
• **JWKS 来源：**Anthropic 如何获取用于验证 JWT 签名的公钥。对于任何在其颁发者 URL 上提供 /.well-known/openid-configuration 的提供商，请使用 discovery（默认值）。使用 explicit_url 直接指向 JWKS 端点，或使用 inline 上传密钥集，适用于无法从公共互联网访问的颁发者（例如私有 Kubernetes 集群）。

颁发者和 JWKS URL 必须使用 https、端口 443，并使用解析为公共 IP 地址的公共 DNS 主机名；不接受 IP 字面量。这些约束仅适用于 Anthropic 需要获取的 URL；在 explicit_url 和 inline 模式下，issuer_url 作为字符串进行比较，可以引用内部主机名。

通常您为每个环境注册一个颁发者：您的生产 EKS 集群、预发布集群和 GitHub Actions 是三个独立的颁发者。



联合规则

联合规则（fdrl_...）是颁发者和服务账号之间的桥梁："当来自颁发者 X 的 JWT 具有符合 Y 特征的声明时，为服务账号 Z 生成一个作用域为 S 的令牌。"

规则定义了匹配条件、目标，以及规则匹配时应用的授权作用域和令牌生命周期：

• **匹配：**传入 JWT 必须满足的条件。您可以匹配 subject_prefix（例如 system:serviceaccount:prod:worker，或以尾部 * 进行前缀匹配）、精确的 audience、精确声明值的映射、用于复杂逻辑的 CEL condition 表达式，或它们的任意组合。必须设置 subject_prefix、claims 或 condition 中的至少一项，且所有已配置的匹配器都必须通过，JWT 才会被接受。
• **目标：**匹配的 JWT 所映射到的服务账号。
• **授权：**在生成的令牌上授予的 OAuth scope。默认值为 workspace:developer，它授予与为该工作区颁发的 API 密钥相同的访问权限。某些产品在您从其流程中创建规则时会锁定作用域；例如，MCP 隧道的创建隧道模态框会创建作用域为 workspace:manage_tunnels 的规则。请参阅 OAuth 作用域。规则还会设置 token_lifetime_seconds（60 到 86400，默认 3600）。

单个颁发者可以有多条规则：每个团队、命名空间或权限级别各一条。规则按 ID 进行评估：客户端在交换请求中指定要使用的规则，Anthropic 验证 JWT 是否满足该规则的匹配条件。不存在隐式的规则搜索。



工作原理

1. **您的 IdP 向工作负载颁发 JWT。**在大多数平台上这是环境自带的：Kubernetes 投影的服务账号令牌、Google Cloud 元数据服务器、Azure IMDS 或 GitHub Actions OIDC 端点。JWT 的 iss 声明标识提供商，其 sub 和其他声明标识具体的工作负载。
2. **SDK 将 JWT 交换为 Anthropic 访问令牌。**SDK 使用 RFC 7523 的 jwt-bearer 授权类型将 JWT 发送到 POST /v1/oauth/token。Anthropic 根据颁发者的 JWKS 和联合规则的匹配条件验证 JWT，然后返回一个短期的 sk-ant-oat01-... 令牌，该令牌代表规则的目标服务账号执行操作。
3. **SDK 在每个请求中发送令牌，并在令牌过期前刷新它。**您的应用程序代码在构造客户端时不传入 api_key，并照常调用 API。SDK 会在令牌过期前重新执行交换。



设置联合

您需要在 Anthropic 组织中具有管理员、所有者或主要所有者角色，一个支持 OIDC 且具有可访问的 JWKS 端点的身份提供商（或者对于隔离集群，一份可粘贴的 JWKS 文档），以及一个能够从该提供商获取身份令牌的工作负载。

Connect workload（连接工作负载）向导会在一个引导式流程中创建全部三种资源（颁发者、服务账号和联合规则），然后端到端验证连接。

要以编程方式管理这些资源，请参阅使用 Admin API 管理 WIF 获取 curl 操作指南，或参阅服务账号 API 参考、联合颁发者 API 参考和联合规则 API 参考以获取完整的参数详情和响应架构。



从您的工作负载进行身份验证

配置好联合后，您的工作负载在运行时将其 IdP 颁发的 JWT 交换为 Anthropic 令牌。SDK 会为您处理交换和刷新循环。cURL 选项卡展示了底层的 HTTP 交换，适用于 shell 脚本、调试或没有 SDK 支持的语言。



构造 SDK 客户端

您可以使用显式凭据或不带任何参数来构造客户端。不带参数时，SDK 会从环境变量或活动配置文件中解析凭据，如凭据优先级中所述。零参数形式是生产工作负载的推荐模式：在所有环境中部署相同的容器镜像，并按环境注入 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID、ANTHROPIC_WORKSPACE_ID 和 ANTHROPIC_IDENTITY_TOKEN_FILE。

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

令牌交换响应遵循 RFC 6749 §5.1。有关字段参考，请参阅令牌交换响应。



凭据优先级

每个 SDK 都按相同的五层顺序解析凭据：构造函数参数，然后是 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN，然后是显式的 ANTHROPIC_PROFILE，然后是联合环境变量，最后是隐式的活动配置文件。第一个产生凭据的来源胜出。

有关完整的优先级表、各层级的语义以及配置文件架构，请参阅 WIF 参考中的凭据优先级。



从 API 密钥迁移

要在不停机的情况下将现有工作负载从静态 API 密钥切换到联合：

1. **并行配置联合。**完成设置指南并确认联合规则与您的工作负载的令牌匹配。暂时保留现有的 ANTHROPIC_API_KEY。
2. **冒烟测试哪个凭据胜出。**从工作负载内部运行 ant auth status（或检查 SDK 调试日志）。由于 ANTHROPIC_API_KEY 在优先级链中位于联合层级之上，此阶段 API 密钥仍会胜出。
3. **在所有注入位置取消设置 ANTHROPIC_API_KEY。**从 CI 密钥、容器环境和 shell 配置文件中删除它（参见前面的警告）。重新运行 ant auth status 并确认现在选择的是联合来源。
4. **撤销 API 密钥。**一旦工作负载在联合令牌上运行，请在 Claude Console 的 Settings → API keys（设置 → API 密钥）下删除该密钥。



令牌生命周期和刷新

生成的 Anthropic 令牌的生命周期取以下两者中的较小值：(a) 规则的 token_lifetime_seconds（默认 3600 秒）和 (b) 您出示的 IdP JWT 剩余生命周期的两倍。结果永远不会少于 60 秒。第二个限制可防止 Anthropic 令牌的存活时间超出其所派生的上游身份太多。

SDK 会缓存令牌，并按照参照 botocore 建模的两层计划进行刷新：

• 建议性刷新在过期前 120 秒。SDK 尝试进行新的交换。如果令牌端点不可达，SDK 会继续使用缓存的令牌，该令牌仍有大约 90 秒的有效期。
• 强制性刷新在过期前 30 秒。此时交换失败会引发错误。缓存的令牌太接近过期，无法安全使用。

由于 SDK 在每次交换时都会重新读取 ANTHROPIC_IDENTITY_TOKEN_FILE，因此它会透明地获取轮换后的投影令牌（例如，Kubernetes 服务账号令牌会在其 exp 之前很早就轮换）。



身份提供商

每份指南涵盖了该平台上 JWT 的来源、其声明的样式，以及需要注册的颁发者和规则配置。



另请参阅

• 使用 Admin API 管理 WIF：通过基础设施即代码创建颁发者、服务账号和规则
• WIF 参考：环境变量、配置文件架构、验证规则和错误代码
• 身份验证：Anthropic SDK 中的所有身份验证选项
• Admin API 参考：每个 Admin API 端点的生成请求和响应架构