在 Kubernetes 中使用 WIF

自管理的 Kubernetes 集群（kubeadm、k3s、OpenShift 以及本地部署的发行版）通过 projected service account tokens（投影服务账户令牌）为每个 Pod 签发 OIDC "JSON Web Token"（JSON Web 令牌），即 JWT。集群的 API 服务器充当 OIDC 颁发者，每个令牌的 sub 声明遵循 system:serviceaccount:<namespace>:<service-account> 的格式。您可以通过读取集群的发现文档来查找其颁发者 URL：

kubectl get --raw /.well-known/openid-configuration | jq -r .issuer

前提条件

• 熟悉 WIF 概念：服务账户、联合颁发者和联合规则。
• 一个在 API 服务器上配置了 --service-account-issuer 标志的 Kubernetes 集群。大多数发行版默认设置此项；kubeadm 集群通常使用 https://kubernetes.default.svc.cluster.local。如果您无法直接访问 API 服务器配置，您的平台团队可以确认该值。
• 满足以下条件之一，以便 Anthropic 能够验证令牌签名：
  • 颁发者的 JWKS 端点可通过公共互联网在 443 端口上以 HTTPS 方式访问，或
  • 您可以从集群内部获取 JWKS 并以 inline 模式注册（在配置 Anthropic 中介绍）。
• 拥有在 Claude Console 中为您的 Anthropic 组织创建服务账户、联合颁发者和联合规则的权限。

配置 Kubernetes

将服务账户令牌投影到您的 Pod 中，并设置联合规则所期望的受众（audience）和生命周期。serviceAccountToken 投影会将新的 JWT 写入挂载路径，并在 expirationSeconds 到期之前轮换它。

apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

为此 Pod 颁发的令牌包含 sub: "system:serviceaccount:inference:inference-worker" 和 aud: ["https://api.anthropic.com"]。

配置 Anthropic

按照设置演练在 Claude Console 中注册联合颁发者、创建 Anthropic 服务账户并创建联合规则。请使用以下 Kubernetes 特定的值。

联合颁发者： 许多自管理集群使用的颁发者 URL（例如 https://kubernetes.default.svc.cluster.local）无法从公共互联网访问。如果您的集群属于这种情况，请选择 inline JWKS 源并粘贴集群的密钥。从集群内部获取它们：

kubectl get --raw /openid/v1/jwks

然后使用返回的 keys 数组的内容（而非外层的 {"keys": [...]} 包装）配置颁发者：

{
  "name": "onprem-k8s",
  "issuer_url": "https://kubernetes.default.svc.cluster.local",
  "jwks_source": "inline",
  "jwks_keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
}

在 inline 模式下，issuer_url 仅用于与 JWT 的 iss 声明进行比较；Anthropic 绝不会尝试访问它。如果您的颁发者可公开访问，请改用 "jwks_source": "discovery" 并省略 jwks_keys。

联合规则： 匹配服务账户的 sub 声明以及您在投影令牌上设置的受众。

{
  "name": "onprem-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

请尽可能根据工作负载的情况进行精确匹配。仅当命名空间中的每个服务账户都应映射到同一个 Anthropic 服务账户时，才将 subject_prefix 放宽为 system:serviceaccount:inference:*（末尾的 * 使其成为前缀匹配）。将规则的 fdrl_... ID 添加到 Pod 的 ANTHROPIC_FEDERATION_RULE_ID 环境变量中。

获取并使用令牌

配置 Kubernetes 中的 Pod 规范将 ANTHROPIC_IDENTITY_TOKEN_FILE 设置为投影挂载路径，同时设置了 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID。配置好这些后，SDK 会在每次交换时从磁盘读取令牌，并自动刷新 Anthropic 访问令牌。

import anthropic

# 读取 ANTHROPIC_IDENTITY_TOKEN_FILE、ANTHROPIC_FEDERATION_RULE_ID、
# ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID 和 ANTHROPIC_WORKSPACE_ID
# （从 Pod 的环境变量中读取）。
client = anthropic.Anthropic()

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

验证设置

成功的交换会返回一个以 sk-ant-oat01- 开头的 access_token 以及一个以秒为单位的 expires_in 值。如果遇到 400 invalid_grant，请参阅排查交换失败问题；Kubernetes 端最常见的原因是 JWKS 密钥不匹配（对于 inline 模式，请使用 kubectl get --raw /openid/v1/jwks 重新获取并更新颁发者）。

限定规则范围

将规则的 match 块锁定到适合您用例的最窄范围：

• 固定命名空间和服务账户名称： 使用完整的 system:serviceaccount:<namespace>:<name> 值，不带末尾的 *。
• 始终设置受众： 在规则上要求 audience，并在 Pod 的 serviceAccountToken 投影上设置相同的值，以便拒绝默认受众令牌。
• 为每个命名空间使用单独的规则： 为每个命名空间创建独立的规则和 Anthropic 服务账户，而不是放宽单个规则的范围。
• 将 inline-JWKS 颁发者限定到单个集群： 当多个集群共享同一个颁发者 URL 时，将每个集群的 JWKS 注册为独立的联合颁发者，并仅将规则绑定到该颁发者。

后续步骤

• Workload Identity Federation：概念、令牌交换流程和 SDK 配置选项。
• WIF 参考：环境变量、JWKS 源模式和规则匹配模式。