Workload Identity Federation

「Workload Identity Federation」（工作負載身分聯合），即 WIF，讓您的工作負載能夠使用短期的「OpenID Connect」（OIDC）權杖向 Claude API 進行驗證，而非使用長期的 sk-ant-... API 金鑰。這些權杖來自您已在運作的「identity provider」（身分提供者），即 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 的建立通道對話框會建立範圍為 org:manage_tunnels 的規則。請參閱 OAuth 範圍。規則也會設定 token_lifetime_seconds（60 至 86400，預設為 3600）。

單一簽發者可以有多個規則：每個團隊、命名空間或權限層級各一個。規則依 ID 評估：用戶端在交換請求中指定要使用的規則，Anthropic 會驗證 JWT 是否滿足該規則的比對條件。沒有隱含的規則搜尋。

運作方式

**您的 IdP 向工作負載簽發 JWT。**在大多數平台上，這是環境自動提供的：Kubernetes 投射的服務帳戶權杖、Google Cloud 中繼資料伺服器、Azure IMDS，或 GitHub Actions OIDC 端點。JWT 的 iss 宣告識別提供者，其 sub 和其他宣告識別特定的工作負載。
**SDK 將 JWT 交換為 Anthropic 存取權杖。**SDK 使用 RFC 7523 的 jwt-bearer 授權類型，將 JWT 發送至 POST /v1/oauth/token。Anthropic 會根據簽發者的 JWKS 和聯合規則的比對條件驗證 JWT，然後回傳一個短期的 sk-ant-oat01-... 權杖，該權杖代表規則的目標服務帳戶執行操作。
**SDK 在每個請求中傳送權杖，並在過期前重新整理。**您的應用程式程式碼在建構用戶端時不帶 api_key，並照常呼叫 API。SDK 會在權杖過期前重新執行交換。

設定聯合

您需要對 Anthropic 組織的管理員存取權限、一個具有可存取 JWKS 端點的 OIDC 身分提供者（或對於隔離叢集，一份可貼上的 JWKS 文件），以及一個能夠從該提供者取得身分權杖的工作負載。

在 Claude Console 中，前往 Settings → Workload identity。

從您的工作負載進行驗證

設定好聯合後，您的工作負載會在執行階段將其 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。

權杖交換回應遵循 RFC 6749 §5.1。欄位參考請參閱權杖交換回應。

憑證優先順序

每個 SDK 都以相同的五層順序解析憑證：建構函式引數，然後是 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN，然後是明確的 ANTHROPIC_PROFILE，然後是聯合環境變數，最後是隱含的作用中設定檔。第一個產生憑證的來源勝出。

ANTHROPIC_API_KEY 位於聯合層級之上，因此環境中殘留的金鑰會悄悄地遮蔽聯合。將工作負載從 API 金鑰遷移至 Workload Identity Federation 時，請確認在該工作負載執行的所有位置（容器環境、CI 密鑰、shell 設定檔）都已取消設定 ANTHROPIC_API_KEY。CLI 的 ant auth status 命令會回報哪個來源勝出。

如需完整的優先順序表、各層級的語意以及設定檔檔案結構描述，請參閱 WIF 參考中的憑證優先順序。

從 API 金鑰遷移

若要在不停機的情況下將現有工作負載從靜態 API 金鑰切換至聯合：

**並行設定聯合。**完成設定逐步說明並確認聯合規則符合您工作負載的權杖。暫時保留現有的 ANTHROPIC_API_KEY。
**煙霧測試哪個憑證勝出。**從工作負載內部執行 ant auth status（或檢查 SDK 除錯記錄）。由於 ANTHROPIC_API_KEY 在優先順序鏈中位於聯合層級之上，此階段 API 金鑰仍會勝出。
**在所有注入位置取消設定 ANTHROPIC_API_KEY。**從 CI 密鑰、容器環境和 shell 設定檔中移除它（請參閱前述警告）。重新執行 ant auth status 並確認現在選取的是聯合來源。
**撤銷 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 的來源、其宣告的樣貌，以及要註冊的簽發者和規則設定。

AWS

STS Web 身分權杖，或 EKS IRSA 投射權杖。

Google Cloud

來自中繼資料伺服器的 Google 簽署身分權杖。

Microsoft Azure

受控身分（IMDS）和 AKS 上的 Entra Workload ID。

另請參閱

WIF 參考：環境變數、設定檔檔案結構描述、驗證規則和錯誤碼
驗證：Anthropic SDK 的所有驗證選項

註冊簽發者

在 Issuers 分頁上，選取 Create issuer。

欄位	值
Name	供您參考的標籤，例如 `prod-eks` 或 `gha`。小寫字母、數字和連字號。
Issuer URL	您的 IdP 在其 JWT 中放置的確切 `iss` 宣告。如果不確定，請解碼範例權杖：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' token`
JWKS source	大多數託管 IdP 使用 `discovery`。僅在無法使用探索時選擇 `explicit_url` 或 `inline`。
Discovery base / JWKS URL / Inline keys	依模式而定。當 IdP 在簽發者 URL 提供 `.well-known` 時，探索模式請留空。
CA cert PEM	僅當您的 IdP 從私有 CA 提供 TLS 時需要。大多數託管 IdP 使用公開 CA，因此請留空。

Console 包含 AWS 和 Google Cloud 的預設設定，會預先填入簽發者 URL 模式和合理的預設規則，另外還有一個通用 OIDC 選項，適用於任何其他符合標準的提供者（例如 GitHub Actions、Kubernetes 服務帳戶簽發者、Microsoft Entra ID 或 Okta）。

建立服務帳戶
前往 Settings → Service accounts → Create service account。提供名稱（例如 inference-worker 或 ci-deploy）和選填的描述。
這是您鑄造的權杖所代表的身分。從每個工作區的 Members 頁面將服務帳戶新增至其應執行操作的工作區。下一步的聯合規則會指定一個工作區，鑄造的權杖範圍限定於該工作區的速率限制和使用量歸屬。請記下服務帳戶 ID（svac_...）。

建立聯合規則

回到 Workload identity 頁面，開啟 Federation rules 分頁並選取 Create rule。

區段	值
Basic info	名稱和選填的描述。選取您在步驟 1 中註冊的簽發者。
Match	選擇 Static 進行主體前綴、受眾和確切宣告比對，或選擇 CEL 使用運算式。請盡可能依據您 IdP 的宣告進行精確設定：比對過於寬鬆的規則會授予超出您預期的存取權限。
Target	選取您在步驟 2 中建立的服務帳戶。
Authorization	OAuth 範圍（預設為 `workspace:developer`，或產品特定的範圍，例如 `org:manage_tunnels`；請參閱 OAuth 範圍）和權杖存留期（以秒為單位）。

請記下規則的 ID（fdrl_...）。您的工作負載會在每個權杖交換請求中傳遞此 ID。

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)