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 中設定的信任規則加以驗證，並回傳一個綁定至您組織中某個服務帳戶的短期 Anthropic 存取權杖。無需鑄造、儲存於 CI、輪替或擔心外洩任何靜態密鑰。

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

概念

在任何工作負載能夠進行聯合之前，您需要在 Claude Console 中設定三項資源。它們共同表達「由簽發者 X 簽署、且宣告（claims）形如 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 精靈會在一個引導式流程中建立全部三項資源（簽發者、服務帳戶與聯合規則），然後端對端驗證連線。

1. 1

   開啟 Connect workload

   在 Claude Console 中，前往 Settings → Workload identity 並選取 Connect workload。

2. 2

   選擇您的提供者

   選取您身分提供者的圖塊：GitHub Actions、AWS、Google Cloud、Microsoft Entra ID 或 Kubernetes。每個圖塊都會預先填入該提供者 JWT 所支援的簽發者 URL 模式與比對欄位。對於任何其他符合標準的提供者（例如 SPIFFE 或 Okta），請選取 Custom OIDC。

3. 3

   填寫引導欄位

   精靈會引導您完成提供者專屬的欄位：簽發者設定、傳入 JWT 的比對條件，以及它所建立的服務帳戶與聯合規則的名稱。精靈會預先填入 oauth_scope=workspace:developer 與 token_lifetime_seconds=600（省略 token_lifetime_seconds 時的 API 預設值為 3600）；若您的工作負載需要不同的範圍或存留時間，請加以調整。

4. 4

   驗證簽發者

   可選擇性地選取 Verify issuer，在建立任何資源之前試執行簽發者設定。驗證會確認 Anthropic 能從您輸入的 URL 擷取並解析 JWKS，從而及早發現可達性與設定錯誤。

5. 5

   測試連線

   精靈會建立簽發者、服務帳戶與聯合規則，然後在 15 分鐘內監聽成功的權杖交換。請在該時間範圍內從您的工作負載觸發一次交換（請參閱從您的工作負載進行驗證）以確認設定正常運作。若時間範圍已過，資源仍會保留；您可以從聯合規則的詳細資料頁面重新執行測試。請記下精靈所建立的規則 ID（fdrl_...）與服務帳戶 ID（svac_...）：您的工作負載在每次權杖交換請求中都會傳遞這兩者，以及您的組織 ID（當規則涵蓋多個工作區時，還需傳遞您的工作區 ID）。

若要以程式化方式管理這些資源，請參閱使用 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 的兩層排程進行重新整理：

• 建議性重新整理於到期前 120 秒進行。SDK 會嘗試新的交換。若權杖端點無法連線，SDK 會繼續提供快取的權杖，該權杖仍有約 90 秒的有效時間。
• 強制性重新整理於到期前 30 秒進行。此時交換失敗會引發錯誤。快取的權杖已太接近到期，不再安全。

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

預設情況下，帶有 jti 宣告的身分權杖為單次使用：每次交換都必須出示一個先前未曾交換過的 JWT，重複出示會在驗證歷史記錄頁面上以 jti_reused 原因失敗。若您的工作負載自行從身分提供者取得權杖，請為每次交換鑄造一個新的 JWT，而非重複使用快取的 JWT（重試迴圈是常見的元凶）。從 ANTHROPIC_IDENTITY_TOKEN_FILE 讀取的權杖亦同：SDK 在每次交換時都會重新讀取該檔案，因此在每次重新整理之前，檔案中必須存有新的權杖。重新讀取到未輪替權杖的重新整理，或重新啟動後再次出示已交換過權杖的程序，都會以相同方式遭到拒絕。在鑄造權杖的存留時間內充分提前輪替權杖，可讓檔案領先於重新整理排程；若您的權杖來源無法如此頻繁地輪替，作為最後手段，您可以為該簽發者停用 check_jti（這會移除該簽發者上每條規則的重放保護）。詳情請參閱 JWT 驗證。

身分提供者

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

另請參閱

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