在 Kubernetes 中使用 WIF

自行管理的 Kubernetes 叢集（kubeadm、k3s、OpenShift 以及地端部署的發行版）會透過投射的服務帳戶權杖（projected service account tokens）為每個 pod 簽署 OIDC JSON Web Token（JWT）。叢集的 API 伺服器會作為 OIDC 簽發者（issuer），而每個權杖的 sub 宣告（claim）遵循 system:serviceaccount:<namespace>:<service-account> 的格式。您可以透過讀取叢集的探索文件（discovery document）來找到叢集的簽發者 URL：

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



先決條件

• 熟悉 WIF 概念：服務帳戶、聯合簽發者（federation issuers）和聯合規則（federation rules）。
• 一個在 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "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 來源模式以及規則比對模式。