Workload Identity Federation

「Workload Identity Federation」（工作負載身分聯合），即 WIF，讓您的工作負載能夠使用短期的 OpenID Connect（OIDC）權杖向 Claude API 進行驗證，而非使用長期的 sk-ant-... API 金鑰。這些權杖來自您已在運作的身分提供者（IdP）：AWS IAM、Google Cloud，或任何符合標準的 OIDC 發行者，例如 GitHub Actions、Kubernetes、SPIFFE、Microsoft Entra ID 或 Okta。

您的工作負載會出示由身分提供者簽署的 JWT。Anthropic 會根據您在 Claude Console 中設定的信任規則驗證該 JWT，並回傳一個短期的 Anthropic 存取權杖，該權杖綁定至您組織中的服務帳戶。無需產生、儲存於 CI、輪替或擔心洩漏任何靜態密鑰。

Workload Identity Federation 透過將靜態 API 金鑰替換為在數分鐘內過期（而非永不過期）的權杖，強化您的安全態勢。但它本身並非完整的安全解決方案：聯合驗證的強度取決於簽署 JWT 的上游身分提供者。請將 Workload Identity Federation 與您的 IdP 已支援的控制措施（工作負載身分綁定、條件式存取、稽核記錄）搭配使用，以實現縱深防禦。



概念

在任何工作負載能夠進行聯合之前，您需要在 Claude Console 中設定三種資源。這些資源共同表達「由發行者 X 簽署、具有類似 Y 宣告的權杖，可以作為服務帳戶 Z 執行操作」。



服務帳戶

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

與 API 金鑰的關鍵區別在於：API 金鑰本身就是憑證，而服務帳戶則是按需為其產生憑證。您可以稽核哪些工作負載以哪個服務帳戶的身分執行操作。



聯合發行者

聯合發行者（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 是三個獨立的發行者。



聯合規則

聯合規則（fdrl_...）是發行者與服務帳戶之間的橋樑：「當來自發行者 X 的 JWT 具有類似 Y 的宣告時，為服務帳戶 Z 產生具有範圍 S 的權杖」。

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

• **比對：**傳入 JWT 必須滿足的條件。您可以比對 subject_prefix（例如 system:serviceaccount:prod:worker，或以結尾 * 進行前綴比對）、確切的 audience、確切宣告值的對應表、用於複雜邏輯的 CEL condition 運算式，或以上任意組合。必須設定 subject_prefix、claims 或 condition 其中至少一項，且所有已設定的比對器都必須通過，JWT 才會被接受。
• **目標：**符合的 JWT 所對應的服務帳戶。
• **授權：**授予所產生權杖的 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 組織中具有管理員、擁有者或主要擁有者角色，一個具有可存取 JWKS 端點的 OIDC 身分提供者（或可貼上的 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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（預設 3600 秒）和 (b) 您出示的 IdP JWT 剩餘存留期的兩倍。結果永遠不會少於 60 秒。第二個限制可防止 Anthropic 權杖的存留期超過其衍生來源的上游身分太多。

SDK 會快取權杖，並依照以 botocore 為模型的兩層排程重新整理：

• 建議性重新整理在過期前 120 秒。SDK 會嘗試新的交換。如果權杖端點無法存取，SDK 會繼續提供快取的權杖，該權杖仍有約 90 秒的有效期。
• 強制性重新整理在過期前 30 秒。此時交換失敗會引發錯誤。快取的權杖太接近過期，無法安全使用。

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



身分提供者

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



另請參閱

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