WIF 參考

本頁彙整了 Workload Identity Federation（工作負載身分聯合）的組態介面、驗證限制與錯誤對應。如需設定逐步教學，請參閱提供者指南。

權杖交換請求

POST /v1/oauth/token 接受使用 RFC 7523 jwt-bearer 授權類型的 JSON 主體。SDK 會根據環境變數為您建構此請求；各提供者指南中的 cURL 範例展示了原始主體。

權杖交換回應

POST /v1/oauth/token 會回傳標準的 OAuth 2.0 權杖回應（RFC 6749 §5.1）：

環境變數

SDK 會讀取這些變數，以在不需建構函式引數的情況下執行聯合權杖交換。

直接環境變數聯合路徑僅在 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID，以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 其中之一全部設定時才會啟用。ANTHROPIC_WORKSPACE_ID 會一併讀取，但不影響啟用條件。

憑證優先順序

SDK 依下列順序解析憑證。第一個產生憑證的來源勝出。

載入設定檔時，環境變數會填補設定檔省略的任何欄位，但絕不會覆寫設定檔明確設定的欄位。例如，ANTHROPIC_WORKSPACE_ID 僅在作用中設定檔未設定 workspace_id 時才會填入該欄位。

設定檔組態檔案

設定檔（profile）是 SDK 與 ant CLI 皆會讀取的具名組態檔案。設定檔讓您能將聯合參數隨容器映像一同發布，或在不變更程式碼的情況下切換環境。

組態目錄

SDK 依下列順序尋找組態目錄：

1. $ANTHROPIC_CONFIG_DIR
2. Linux 與 macOS 上的 ~/.config/anthropic
3. Windows 上的 %APPDATA%\Anthropic

作用中設定檔

作用中設定檔名稱依下列順序解析：

1. $ANTHROPIC_PROFILE
2. <config_dir>/active_config 的內容（由 ant profile activate <name> 寫入的單行檔案）
3. 字面名稱 default

Claude Code 與 Claude Agent SDK 遵循相同的解析順序，因此在此設定的聯合設定檔也能在無需額外設定的情況下為這些工具進行驗證。

檔案配置

組態檔案與憑證檔案皆帶有頂層字串 version 欄位，格式為 major.minor（目前為 "1.0"）。SDK 會自動寫入此欄位，以便未來版本能偵測並遷移較舊的格式；手動撰寫組態時可省略此欄位，SDK 會將該檔案視為目前版本。

聯合設定檔範例

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

若省略 authentication.identity_token，SDK 會退回至環境中的 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN。

OAuth 範圍

您在聯合規則上設定的 oauth_scope 決定了鑄造的存取權杖可呼叫哪些 Claude API 端點。

對權杖範圍以外的端點發出請求會回傳 HTTP 403。目前尚未提供更細緻的範圍（依資源，或讀取與寫入之分）。

權限邊界

聯合規則的 oauth_scope 是上限：鑄造的權杖絕不會超過它。目標服務帳戶的 organization_role（developer 或 admin）決定了可授予哪些範圍，因此授予 org:admin 的規則必須以 organization_role=admin 的服務帳戶為目標。有效權限為規則範圍與服務帳戶角色的交集。

驗證規則

Anthropic 會在您建立或更新簽發者與規則時，以及在交換時驗證傳入的 JWT 時，強制執行這些限制。

如需完整的參數細節與回應結構描述，請參閱 Service accounts API 參考、Federation issuers API 參考與 Federation rules API 參考。

資源欄位

URL 欄位

issuer_url、jwks.discovery_base 與 jwks.url 欄位會經過驗證：

URL 驗證失敗會回傳 400 invalid_request_error，並以欄位名稱作為錯誤訊息的前綴（例如 issuer_url: url must use https scheme）。

JWT 驗證

規則比對語意

聯合規則的 match 區塊決定是否接受傳入的 JWT。所有已填入的欄位皆以 AND 語意評估：JWT 必須滿足每一個已填入的比對器。subject_prefix、claims 或 condition 至少須設定其中之一；僅包含 audience（或完全沒有比對器）的 match 區塊會被拒絕。這可防止規則接受來自某簽發者的所有權杖。

CEL 評估環境

condition 運算式可存取單一變數：

範例：

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

錯誤

權杖交換錯誤

POST /v1/oauth/token 以標準的 API 錯誤格式回傳錯誤。SDK 會將交換失敗包裝為具型別的 FederationExchangeError（或各語言的對等型別），其中公開 HTTP 狀態、回應主體與 request_id。

無論是哪一項檢查失敗，每個斷言拒絕皆回傳相同的不透明 401 authentication_error，並帶有固定訊息 Authentication failed；可區分的錯誤會讓呼叫者得以探測規則組態。拒絕原因會記錄在驗證歷程記錄中該次嘗試的項目上，例如當 sub 宣告未通過規則的 subject_prefix 時為 match_subject_prefix，或當規則橫跨多個工作區而請求未指定任何工作區時為 workspace_id_required。在規則所屬組織獲得確認之前即被拒絕的請求（上述 400 invalid_request_error 系列）不會留下歷程記錄項目；其回應訊息會直接指出問題。沒有對應歷程記錄項目的 401 通常表示 federation_rule_id 本身未被識別。

常見的 SDK 端失敗

疑難排解失敗的交換

401 authentication_error 回應刻意設計為不透明，其訊息一律為 Authentication failed；拒絕原因記錄在驗證歷程記錄中，而非回應中。

一種常見的不透明失敗是重送的斷言：帶有 jti 宣告的斷言只能交換一次，因此重新傳送相同 JWT 的工作負載（重試迴圈，或重新讀取未輪替權杖的重新整理）會在第二次交換時被拒絕。驗證歷程記錄頁面會以原因 jti_reused 顯示這些嘗試；修正方式是為每次交換鑄造新的斷言。

若您仍需從 JWT 本身進行除錯，請依序進行下列檢查：

1. 1

   解碼 JWT

   解碼您所傳送的斷言，以便將每個宣告與您的簽發者及規則組態比對：

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   檢查 iss 是否與簽發者相符

   解碼後的 iss 宣告必須與已註冊的 issuer_url 逐位元組相等，包含配置、連接埠與任何結尾斜線。單一字元不符即會導致驗證失敗。

3. 3

   檢查 aud 是否與規則相符

   解碼後的 aud 宣告必須包含規則的 audience 值且完全相符。當 aud 為陣列時，必須有一個元素完全相符。

4. 4

   檢查 sub 與每個 claims 項目

   將 sub 與規則的 subject_prefix 比對（區分大小寫；結尾的 * 為前綴比對，其他情況為完全比對）。將規則 claims 對應中的每個鍵與同名的頂層宣告比對。

5. 5

   檢查 exp、nbf 與 iat

   exp 必須為未來時間，nbf/iat 必須為過去時間，且在 30 秒偏差視窗內。若工作負載主機的時鐘已漂移，原本有效的權杖也會被拒絕。

6. 6

   檢查 JWKS 可連線性

   對於 discovery 模式，請透過連接埠 443 的公開 HTTPS 擷取 <jwks.discovery_base or issuer_url>/.well-known/openid-configuration，並確認 jwks_uri 可解析。對於 explicit_url，請直接擷取 JWKS URL。對於 inline，請確認簽發者的簽署金鑰自您註冊金鑰以來未曾輪替。

   若簽發者輪替了簽署金鑰並立即開始以其簽署，在 Anthropic 的 JWKS 快取重新整理期間，交換可能會失敗長達一分鐘。請參閱金鑰輪替與快取。

JWKS 來源模式

當您註冊聯合簽發者時，jwks 欄位控制 Anthropic 如何取得用於驗證該簽發者 JWT 簽章的公開金鑰。它是以 type 為鍵的可辨識聯集（discriminated union）：

可辨識聯集在結構上使各伴隨欄位互斥。discovery 與 explicit_url 也都接受選填的 ca_cert_pem 字串，供以私有 CA 提供 TLS 的簽發者使用。

金鑰輪替與快取

在 discovery 與 explicit_url 模式下，Anthropic 會快取擷取到的 JWKS。若您的身分提供者發布新的簽署金鑰並立即開始以其簽署權杖，在快取重新整理期間，出示這些權杖的交換可能會因簽章錯誤而失敗長達 1 分鐘。

為避免此空窗期，請在您的身分提供者開始以新簽署金鑰簽署權杖前至少 15 分鐘，先在 JWKS 中發布該金鑰，並將被取代的金鑰保留在 JWKS 中，直到其所簽署的權杖皆已到期。受管身分提供者通常會自行遵循此規範。若您自行營運簽發者（自行管理的 Kubernetes 叢集、SPIRE OIDC 探索提供者，或設定了輪替週期的 Okta 自訂授權伺服器），請確認您的輪替政策會在首次使用前先發布新金鑰。