在 Kubernetes 中使用 WIF

自行管理的 Kubernetes 叢集（kubeadm、k3s、OpenShift 以及本地部署的發行版）會透過投射的服務帳戶權杖為每個 Pod 簽署 OIDC「JSON Web Token」（JSON 網路權杖），即 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 端點可透過 HTTPS 在連接埠 443 上從公開網際網路存取，或
  • 您可以從叢集內部擷取 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 中，開啟 Settings → Workload identity，點擊 Connect workload，然後選擇 Kubernetes 圖塊。精靈會引導您完成註冊簽發者、建立服務帳戶和建立聯合規則的步驟。

精靈會為您建立這些資源。無論您是在精靈中輸入這些值，還是將其傳送至 Admin API，請使用以下值：

聯合簽發者： 許多自行管理的叢集使用無法從公開網際網路存取的簽發者 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": {
    "type": "inline",
    "keys": [{ "kty": "RSA", "kid": "...", "n": "...", "e": "AQAB" }]
  }
}

在 inline 模式下，issuer_url 僅用於與 JWT 的 iss 宣告進行比對；Anthropic 絕不會嘗試連線到該 URL。如果您的簽發者可公開存取，請改用 "jwks": {"type": "discovery"}。

聯合規則： 比對服務帳戶的 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 來源模式和規則比對模式。