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 依下列順序解析憑證。第一個產生憑證的來源勝出。

在 ant CLI 中，Claude Models on Google Cloud (Anthropic managed) 的設定優先順序排在聯合（federation）環境變數之後、作用中設定檔之前。這些設定包括專案、工作區 ID 和位置。您可以使用 --google-cloud-* 旗標或 ANTHROPIC_GOOGLE_CLOUD_* 變數來設定它們。只要設定了其中任何一項，CLI 就會使用這些設定。使用這些設定時，CLI 會從 Google Application Default Credentials 取得其憑證。

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

設定檔組態檔案

設定檔是 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 會將交換失敗回報為 WorkloadIdentityError，其中提供 HTTP 狀態以及回應主體中的錯誤詳細資訊。在 Python、TypeScript 與 Ruby 中，請求 ID 位於錯誤物件上；在 Java 中則位於例外的回應標頭中。在 Go 中，它只出現在錯誤訊息中，因為錯誤的類型位於內部套件；C# 與 PHP 的錯誤則不包含請求 ID。

每次斷言遭拒都會傳回相同的不透明 401 authentication_error，並帶有固定訊息 Authentication failed，無論是哪項檢查失敗；可區分的錯誤會讓呼叫者得以探測規則組態。拒絕原因會記錄在 Claude Console 中驗證歷程記錄的該次嘗試項目上，例如當 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 為鍵的可辨識聯集：

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

金鑰輪替與快取

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

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