Workload Identity Federation

"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 中、轮换或担心泄露。

Workload Identity Federation 通过用几分钟内过期（而非永不过期）的令牌替换静态 API 密钥来增强您的安全态势。它本身并不是一个完整的安全方案：联合身份验证的强度取决于签署 JWT 的上游身份提供商。请将 Workload Identity Federation 与您的 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 组织中拥有 admin、owner 或 primary owner 角色，一个具有可访问 JWKS 端点的支持 OIDC 的身份提供商（或者对于隔离网络的集群，一个可以粘贴的 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "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 下删除该密钥。



令牌生命周期和刷新

铸造的 Anthropic 令牌的生命周期取以下两者中的较小值：(a) 规则的 token_lifetime_seconds（默认 3,600 秒）和 (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 端点的生成请求和响应模式