Workload Identity Federation

「Workload Identity Federation」（工作負載身分聯合），即 WIF，讓您的工作負載能夠使用短期的 OpenID Connect（OIDC）權杖（而非長期的 sk-ant-... API 金鑰）向 Claude API 進行驗證。這些權杖來自您已經在運作的身分提供者（identity provider，即 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 行動」。



服務帳戶

「Service account」（服務帳戶，svac_...）是您 Anthropic 組織內一個具名的非人類身分。它是聯合權杖所代表的主體。服務帳戶存在於組織層級，當您將它們新增為某個工作區的成員時，便會在該工作區中生效。在交換時，Anthropic 會檢查聯合規則的工作區是否符合該服務帳戶的其中一個工作區成員資格；鑄造出的權杖隨後會遵循該工作區的速率限制和用量歸屬，與 API 金鑰相同。與人類使用者不同，服務帳戶沒有電子郵件、沒有密碼，也無法登入 Console。每個服務帳戶都隱含地是您組織預設工作區的成員；若要讓它在其他工作區中行動，請新增明確的成員資格。

與 API 金鑰的關鍵區別在於：API 金鑰本身就是一個憑證，而服務帳戶則是擁有依需求為其鑄造的憑證。您可以稽核哪些工作負載以哪個服務帳戶的身分行動。



聯合簽發者

「Federation issuer」（聯合簽發者，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 是三個獨立的簽發者。



聯合規則

「Federation rule」（聯合規則，fdrl_...）是簽發者與服務帳戶之間的橋樑：「當來自簽發者 X 的 JWT 具有看起來像 Y 的宣告時，為服務帳戶 Z 鑄造一個具有範圍 S 的權杖。」

規則定義了比對條件、目標，以及規則比對成功時適用的授權範圍和權杖存留期：

• 比對（Match）： 傳入的 JWT 必須滿足的條件。您可以比對 subject_prefix（例如 system:serviceaccount:prod:worker，或在結尾加上 * 進行前綴比對）、精確的 audience、精確宣告值的對應表、用於複雜邏輯的 CEL condition 運算式，或任意組合。subject_prefix、claims 或 condition 至少必須設定其中一項，且所有已設定的比對器都必須通過，JWT 才會被接受。
• 目標（Target）： 比對成功的 JWT 所對應的服務帳戶。
• 授權（Authorization）： 授予鑄造權杖的 OAuth scope。預設值為 workspace:developer，授予與為該工作區簽發的 API 金鑰相同的存取權限。某些產品在您從其流程建立規則時會鎖定範圍；例如，MCP tunnels 的建立通道對話框會建立範圍為 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 角色、一個具備 OIDC 能力且 JWKS 端點可存取的身分提供者（或對於隔離網路的叢集，一份可以貼上的 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 的兩層排程重新整理：

• 建議性重新整理（Advisory refresh）：在到期前 120 秒。SDK 嘗試進行新的交換。如果權杖端點無法連線，SDK 會繼續使用快取的權杖，該權杖仍有大約 90 秒的有效時間。
• 強制性重新整理（Mandatory refresh）：在到期前 30 秒。此時交換失敗會引發錯誤。快取的權杖太接近到期時間，不再安全。

由於 SDK 在每次交換時都會重新讀取 ANTHROPIC_IDENTITY_TOKEN_FILE，它會透明地取得已輪替的投射權杖（例如，Kubernetes 服務帳戶權杖會在其 exp 之前很早就輪替）。



身分提供者

每份指南都涵蓋該平台上 JWT 的來源、其宣告的樣貌，以及要註冊的簽發者和規則設定。



另請參閱

• 使用 Admin API 管理 WIF：從基礎設施即程式碼建立簽發者、服務帳戶和規則
• WIF 參考：環境變數、設定檔檔案結構描述、驗證規則和錯誤代碼
• 驗證：Anthropic SDK 中的所有驗證選項
• Admin API 參考：每個 Admin API 端點的產生請求和回應結構描述