Claude Code Workload Identity Federation 配置指南：用 OIDC 替换静态 Key

如果你的基础设施仍在用长期有效的 sk-ant-... key 认证 Claude API，Anthropic 现在提供了彻底消除这一风险的机制。Anthropic Claude workload identity federation（WIF）允许任何支持 OIDC 的工作负载——GitHub Actions runner、Kubernetes Pod、AWS Lambda——在运行时用云身份 token 换取短期 Anthropic 访问凭证。不需要存储静态密钥，不需要手动轮换，每次 API 调用都归属到组织内的命名 service account。

如果你正在搜索如何为 Claude Code、Claude Code Action 或路由 gateway 配置 workload identity federation，实际路径是：创建 Anthropic service account，注册工作负载的 OIDC issuer，用 federation rule 约束 claims，然后用 WIF 环境变量替代 ANTHROPIC_API_KEY 运行 Claude 客户端。

对路由团队来说，这不仅改变了如何认证 Claude，更改变了 gateway 或 proxy 层应如何存储和注入下游 Claude API 凭证的方式。

如何配置 Claude Code workload identity federation

最短路径是使用 Claude Console 的 Settings → Workload identity → Connect workload 向导。它适用于 GitHub Actions 中的 Claude Code Action、运行在 Kubernetes 的 Claude Code agent，或代表开发者调用 Claude 的 gateway：

1. 创建或选择 Anthropic service account。 这是 Claude Code 或 gateway 将要扮演的非人类 principal。测试 token exchange 前，先把它加入目标 workspace。
2. 注册工作负载的 OIDC issuer。 Claude Code Action 通常使用 GitHub Actions issuer（https://token.actions.githubusercontent.com）。Kubernetes 使用 cluster service-account issuer。AWS、Google Cloud、Entra ID、Okta 或 SPIFFE 可选择对应 provider tile 或 Custom OIDC。
3. 收紧 federation rule。 精确匹配 GitHub repository/ref、Kubernetes namespace/service account 或云工作负载身份。不要使用过宽的 subject_prefix，否则无关 job 也可能铸造 Claude token。
4. 设置 OAuth scope 和 token lifetime。 推理请求通常使用 workspace:developer。MCP tunnel 管理需要 org:manage_tunnels，不要盲目复用同一条 rule。先使用 600–3600 秒有效期，再根据负载测试调整。
5. 运行时注入 WIF 环境变量。 配置 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID、ANTHROPIC_WORKSPACE_ID 和 ANTHROPIC_IDENTITY_TOKEN_FILE，然后用不传 api_key 的 SDK client。
6. 从真实工作负载验证。 在向导测试窗口内触发 Claude Code Action、CI job、Pod 或 gateway deployment。必须由真实 identity provider 完成 exchange，而不是只在本地 shell 验证。

如果你配置的是 Claude Code Action，最需要避免的失败模式是信任整个 GitHub organization 的所有 Actions token。应把 federation rule 绑定到明确的 repository、branch/tag 策略、environment 和 workflow claims。

发生了什么

Anthropic 在 Claude Console 的 Settings → Workload identity 下发布了 workload identity federation 的完整文档。该功能采用三资源模型，与 GCP Workload Identity Federation 和 AWS IRSA 的模式基本一致：

Service accounts（svac_...） — 组织内的非人类身份。没有邮箱、没有密码、无法登录 Console。加入某个 workspace 后即在该 workspace 激活；token 交换时，Anthropic 铸造一个短期 token，该 token 受该 workspace 的速率限制和用量归属约束。

Federation issuers（fdis_...） — 已注册的 OIDC 身份提供商。每个环境注册一个 issuer（生产 EKS 集群、测试集群、GitHub Actions 各为独立 issuer）。issuer 记录将 iss claim 值映射到 JWKS 源，供 Anthropic 验证 JWT 签名。

Federation rules（fdrl_...） — 连接 issuer 与 service account 的桥梁："来自 issuer X、claim 匹配 Y 的 JWT，可以作为 service account Z 操作。"规则定义匹配条件（subject_prefix、audience、精确 claim 值或 CEL 表达式）、目标 service account、OAuth scope（默认 workspace:developer）及 token 有效期（60–86400 秒，默认 3600 秒）。

交换流程遵循标准 RFC 7523 jwt-bearer：工作负载将 IdP 签发的 JWT 连同 federation rule ID、org ID、service account ID 和 workspace ID 一起 POST 到 /v1/oauth/token，Anthropic 返回 sk-ant-oat01-... 访问 token。Anthropic SDK 处理交换和自动刷新；应用代码不传 api_key 参数，直接调用 API。

开箱即用的 issuer 包括 AWS IAM、Google Cloud、GitHub Actions、Kubernetes service account issuer、SPIFFE、Microsoft Entra ID 和 Okta。隔离集群可使用 explicit_url 或 inline JWKS 模式。

对 AI 工程团队的意义

静态 API key 是大多数 AI 基础设施中最大的未解决凭证风险。 sk-ant-... key 通常存储在环境变量、Kubernetes Secret 或 CI 密钥里，永不过期。一旦泄露——无论是 git commit、日志行、容器镜像检查还是被攻击的构建产物——攻击者在手动轮换之前都有无限访问权。Workload identity federation 从根本上消除了这类风险，适用于已有 OIDC 身份的工作负载。

Token 有效期控制提供了范围化的时效访问。 默认 3600 秒有效期意味着即使 token 泄露，最多一小时内失效。CI 短任务可降至 60 秒。对于长期运行的 agent 工作流，SDK 在过期前自动重新交换。

Service account 让 AI API 调用可审计。 目前多数团队将 Claude API 调用归属到单一 API key，难以回答"上周二哪个部署产生了这些 token 消耗？"使用 service account 后，每个工作负载映射到命名 principal，结合 workspace 级别速率限制，能精细区分调用来源。

CEL 匹配条件支持细粒度访问规则。 若 Kubernetes 集群同时运行生产和测试工作负载，可创建带有 CEL 表达式的独立规则，按 namespace 标签、环境 claim 或具体 service account 名称匹配，分别映射到不同 Anthropic service account 与不同 workspace。

Router/Operator 视角

对于通过 gateway 或 proxy 层路由 Claude 流量的团队，workload identity federation 以具体且值得现在规划的方式改变了凭证模型。

你的 gateway 是 WIF 采用的首要候选。 路由 gateway 代表上游客户端发出 Claude API 调用，通常持有一个静态 sk-ant-... key 并注入到转发请求中。如果 gateway 运行在 AWS、GCP 或 Azure 上，它本就有 OIDC 身份（IAM role、service account 或 managed identity）。注册为 WIF issuer，创建 gateway 的 service account，设置 federation rule，然后通过环境变量配置 SDK：

export ANTHROPIC_FEDERATION_RULE_ID="fdrl_..."
export ANTHROPIC_ORGANIZATION_ID="00000000-0000-0000-0000-000000000000"
export ANTHROPIC_SERVICE_ACCOUNT_ID="svac_..."
export ANTHROPIC_WORKSPACE_ID="wrkspc_..."
export ANTHROPIC_IDENTITY_TOKEN_FILE="/var/run/secrets/anthropic.com/token"

SDK 零参数构造函数从这些环境变量中解析凭证，处理交换，并在过期前自动刷新。gateway 不再存储长期有效的 key。

Workspace 作用域让团队隔离成为凭证原语，而非仅仅是路由标签。 若你为不同团队或成本中心运行独立的 Anthropic workspace，WIF 支持为每个 workspace 创建独立 service account、为每个部署创建独立 federation rule。路由到 team-a workspace 的请求使用 team-a service account token，路由到 team-b 的使用 team-b token。速率限制、用量归属和访问控制随 workspace 走，而不仅仅是路由标签。

MCP tunnel 集成需要特定 scope。 若通过 MCP tunnel 使用 Claude Code 或其他 agent，tunnel 流程创建的 federation rule 使用 org:manage_tunnels scope，而非 workspace:developer。构建同时代理推理和 tunnel 管理调用的路由层时，需为每个 scope 设置独立 federation rule（并可能使用独立 service account）。默认 workspace:developer scope 不包含 tunnel 管理权限。

Token 交换延迟是唯一需要评估的运营成本。 每次 WIF 交换是一次到 POST /v1/oauth/token 的 HTTP 往返。在默认 3600 秒有效期下，SDK 缓存并自动刷新，每个 token 的开销分摊到数千次请求，对高吞吐 gateway 几乎可忽略。对于极短 request batch 或冷启动路径，在容量规划时需考虑首次交换延迟。

Operator 迁移检查清单：

1. 识别已有 OIDC 身份的工作负载。 检查 gateway、CI/CD 流水线和 Claude Code 部署是否持有 AWS IAM role、GCP service account、GitHub Actions OIDC 或 Kubernetes projected token。
2. 每个环境注册一个 issuer。 为生产、测试和 CI 分别创建 fdis_... 记录，防止测试凭证铸造生产 workspace 的 token。
3. 每个团队或成本中心映射一个 service account。 将 service account 加入对应 Anthropic workspace，速率限制和用量归属自动跟随。
4. 共享 issuer 使用 CEL 条件。 若单一 Kubernetes 集群服务多个团队，使用 CEL condition 表达式按 namespace 或标签 claim 匹配，而非宽泛的 subject_prefix。
5. 更新 gateway SDK 构造方式。 将 api_key=os.environ["ANTHROPIC_API_KEY"] 替换为零参数构造函数，按环境注入 ANTHROPIC_FEDERATION_RULE_ID 等环境变量。
6. 在负载下测试 token 有效期。 初始设为 3600 秒。对高吞吐 gateway，在降低有效期前确认 SDK 刷新时序在并发场景下不产生竞争。
7. 单独验证 MCP tunnel scope。 若部署包含 MCP tunnel，确认 tunnel federation rule 使用 org:manage_tunnels scope，且映射到具有 org 级别成员身份的 service account。

TheRouter 用户应关注或尝试的内容

Workload identity federation 对于通过路由层运行 Claude Code 或 Claude 支持的 agent 工作流的团队最具可操作性。若你的部署运行在已有 OIDC 身份的云环境中，可以从 AI provider 路由 配置中消除静态 sk-ant-... key，改用 SDK 零参数模式的 token 交换流程。

对于在 OpenAI 和 Anthropic 之间做多 provider 路由的团队，值得注意：两家 provider 现在都有基于 OIDC 的无密钥认证——但实现不同。OpenAI 在 organization 级别使用自己的 workload identity federation 流程；Anthropic 使用 service account + federation rule 加 CEL 匹配条件和 workspace 级别作用域。在同一 gateway 管理两家 provider 的团队需要为每家 provider 独立配置 federation。

Anthropic Claude Console 的 Settings → Workload identity 文档是权威的配置指南。关注 Anthropic changelog 中关于 OAuth scope 更新、新预设身份提供商及 token 有效期约束调整的动态。