管理驗證

WIF 參考

Workload Identity Federation 的環境變數、驗證規則、設定檔配置與錯誤參考。

本頁彙整了 Workload Identity Federation 的配置介面、驗證限制與錯誤對應。如需設定逐步說明，請參閱供應商指南。

權杖交換請求

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

欄位	必填	說明
`grant_type`	是	一律為 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	是	由您的身分提供者核發的 OIDC JWT。
`federation_rule_id`	是	要評估之聯合規則的標記 ID（`fdrl_...`）。
`organization_id`	是	您的 Anthropic 組織的 UUID。
`service_account_id`	是	目標服務帳戶的標記 ID（`svac_...`）。
`workspace_id`	視情況而定	要將鑄造的權杖限定範圍至的工作區標記 ID（`wrkspc_...`），或使用字面值 `default` 表示組織的預設工作區。當規則啟用於多個工作區時為必填。若省略，伺服器會選取該規則唯一啟用的工作區。

權杖交換回應

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

欄位	類型	說明
`access_token`	string	短期有效的 Anthropic 權杖，前綴為 `sk-ant-oat01-...`。以 `Authorization: Bearer <token>` 的形式傳遞。
`token_type`	string	一律為 `Bearer`。
`expires_in`	integer	權杖到期前的秒數。
`scope`	string	由符合的規則所授予的 OAuth 範圍。

環境變數

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

變數	必填	說明	範例
`ANTHROPIC_FEDERATION_RULE_ID`	是	要評估之聯合規則的標記 ID。	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	是	您的 Anthropic 組織的 UUID。可在 Claude Console 的 Settings > Organization 下找到。	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	由您的「identity provider」（身分提供者），即 IdP 所核發之 JWT 的檔案系統路徑。SDK 會在每次交換時重新讀取此檔案，以確保在磁碟上輪替的投射權杖始終為最新。	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	以字串形式提供的 JWT 字面值。當您的平台以環境變數而非檔案的方式注入權杖時使用。	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	是	目標 Anthropic 服務帳戶的標記 ID，核發的存取權杖將以此帳戶身分運作。	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	視情況而定	要將鑄造的權杖限定範圍至的工作區標記 ID，或字面值 `default`。當聯合規則啟用於多個工作區時為必填；當規則僅繫結至單一工作區時為選填。鑄造的權杖在交換時即限定於此工作區，因此切換工作區需要進行新的交換。	`wrkspc_...`
`ANTHROPIC_PROFILE`	否	要載入的配置設定檔名稱。優先於本表中的聯合環境變數。	`staging-profile`

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

設定為空字串的變數仍會佔據其在憑證優先順序鏈中的位置。如果匯出了 ANTHROPIC_API_KEY=""，SDK 會選擇 API 金鑰路徑並使用空金鑰，而不會繼續往下嘗試聯合。請取消設定未使用的憑證變數，而非將其設為空白。

憑證優先順序

SDK 會依此順序解析憑證。第一個產生憑證的來源即為採用對象。

順序	來源	備註
1	建構函式引數（`api_key=`、`auth_token=`、`credentials=`）	一律覆寫其他所有來源。
2	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`	完全遮蔽聯合。從 API 金鑰遷移時請取消設定這些變數。
3	`ANTHROPIC_PROFILE`	載入 `<config_dir>/configs/<name>.json`。找不到指定名稱的設定檔會產生錯誤，而非繼續往下嘗試。
4	聯合環境變數	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`。
5	作用中設定檔	從 `<config_dir>/active_config` 解析，若無則回退至名為 `default` 的設定檔。

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

設定檔配置檔案

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

配置目錄

SDK 會依此順序尋找配置目錄：

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

作用中設定檔

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

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

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

檔案配置

路徑	內容	敏感性
`<config_dir>/configs/<profile>.json`	`version`、`authentication` 區塊、`organization_id`、`workspace_id` 與 `base_url`。	非機密。可安全提交或內建至映像中。
`<config_dir>/credentials/<profile>.json`	`version`、快取的 `access_token`、`expires_at`，以及（用於互動式登入的）`refresh_token`。	機密。由 SDK 以 `0600` 模式寫入。

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

聯合設定檔範例

configs/production.json

{
  "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 端點。

範圍	授予存取權限
`workspace:developer`	規則工作區中所有非管理性的 Claude API 端點：Messages（包含串流與權杖計數）、Models、Managed Agents 及其工作階段、Files，以及 Skills。這與為相同工作區核發的 API 金鑰所擁有的存取權限相符。
`org:manage_tunnels`	MCP 通道 API：列出與取得通道、註冊與封存 CA 憑證、顯示與輪替通道權杖，以及封存通道。當您從 Console 的建立通道對話框建立規則時，該對話框會鎖定此範圍。

對權杖範圍以外端點的請求會傳回 HTTP 403。目前不提供更細緻的範圍（按資源劃分，或讀取與寫入區分）。

驗證規則

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

資源欄位

欄位	限制
發行者、規則與服務帳戶的 `name`	必須符合 `^[a-z0-9-]+$`，長度為 1 至 255 個字元。
`workspace_id`	選填。其配額、計費與速率限制適用於依此規則鑄造之權杖的工作區（`wrkspc_...`）。必須是同一組織中的工作區，且目標服務帳戶必須是該工作區的成員。對於僅配置單一工作區的規則可省略。
`token_lifetime_seconds`	介於 `60` 與 `86400` 之間的整數（1 分鐘至 24 小時）。預設為 `3600`。超出此範圍的值會在請求時被拒絕。請參閱權杖存留期與重新整理。

URL 欄位

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

限制	詳細說明
協定	必須為 `https`。
連接埠	必須為 `443`（明確指定或預設）。
主機	必須是您的 OIDC 提供者的公開 DNS 主機名稱。必須解析為公開 IP 位址；不接受 IP 字面值。

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

URL 限制僅適用於 Anthropic 會連線的 URL。在 explicit_url 與 inline JWKS 模式中，以及在設定了 jwks.discovery_base 的 discovery 模式中，issuer_url 僅以字串形式與 JWT iss 宣告進行比對，且絕不會被擷取，因此可以參照內部主機名稱或非標準連接埠。

JWT 驗證

限制	詳細說明
最大大小	`assertion` JWT 最多為 16 KiB。
簽署演算法	僅接受非對稱演算法（RSA 與 ECDSA 系列：ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512）。HMAC（`HS256`、`HS384`、`HS512`）與 `none` 會被拒絕。
金鑰 ID	JWT 標頭必須帶有與發行者 JWKS 中某個金鑰相符的 `kid`。沒有 `kid` 的權杖會被拒絕。
必要宣告	`sub` 必須存在。`iat` 必須存在且不在未來。`exp` 必須存在且在未來。
最大存留期	權杖的存留期（`exp` 減去 `iat`）不得超過發行者配置的最大值（預設為 1 小時，可在 Claude Console 中為每個發行者配置）。
時鐘偏差	對 `exp`、`nbf` 與 `iat` 套用 30 秒的容許範圍。

規則比對語意

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

比對器	類型	語意
`subject_prefix`	string	與 JWT `sub` 宣告進行完全比對。結尾的 `` 使其成為前綴比對（`sub` 值必須以 `` 之前的字元開頭）。區分大小寫。
`audience`	string	JWT `aud` 宣告必須包含此完全相符的字串。當 `aud` 為陣列時，任何完全相符的元素即滿足檢查。
`claims`	map<string, string>	每個鍵是頂層宣告名稱，每個值是所需的完全相符字串值。對於巢狀、數值、布林或如清單與對應等複雜宣告，請改用帶有 CEL 運算式的 `condition`。
`condition`	string (CEL)	必須評估為 `true` 的 CEL 運算式。

CEL 評估環境

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

變數	類型	內容
`claims`	map	完整解碼的 JWT 宣告集。巢狀物件可作為巢狀對應存取。

範例：

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

CEL 條件是安全邊界。對超出預期範圍的輸入評估為 true 的運算式，會授予超出預期的存取權限。當靜態比對器能表達您的限制時，請優先使用它們。

錯誤

權杖交換錯誤

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

狀態	錯誤	原因	解決方式
400	`invalid_request`	`federation_rule_id` 格式錯誤，或缺少必要的請求欄位。	驗證 `fdrl_` ID，並確認請求主體包含所有必要欄位。
400	`invalid_request`	`workspace_id_required`：聯合規則啟用於多個工作區，而請求省略了 `workspace_id`。	將 `ANTHROPIC_WORKSPACE_ID`（或原始請求中的 `workspace_id` 主體欄位）設定為您希望權杖限定範圍至的 `wrkspc_...` ID。請參閱權杖交換請求。
400	`invalid_grant`	JWT `iss` 宣告與註冊的 `issuer_url` 不完全相等。	逐位元組比對，包含結尾斜線與協定：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKS 擷取失敗、JWKS 已過時，或 JWT 使用不在 JWKS 中的金鑰簽署。	對於 `inline` 模式，請使用輪替後的金鑰更新發行者。對於 `discovery` 與 `explicit_url`，請確認 JWKS 端點可透過連接埠 443 存取；如果發行者最近輪替了其簽署金鑰，請參閱金鑰輪替與快取。
400	`invalid_grant`	JWT `exp` 宣告已過期（超出 30 秒偏差範圍）。	確認您的身分提供者正在投射新的權杖，且 SDK 正在重新讀取權杖檔案。
400	`invalid_grant`	JWT 已通過驗證，但其宣告不滿足規則的 `match` 區塊。	解碼 JWT 並將每個宣告與規則進行比對。`subject_prefix` 區分大小寫。`audience` 需要完全相符的元素比對。
400	`invalid_grant`	`federation_rule_id` 不存在、已封存，或 JWT 未獲授權使用該規則（合併處理以防止列舉）。	在 Claude Console 中確認規則 ID，並確認該規則尚未被封存。

所有 invalid_grant 失敗都會傳回 HTTP 400；具體原因僅記錄於伺服器端，不會在回應中公開。

常見的 SDK 端失敗

症狀	原因	解決方式
SDK 回報「no credentials」而非進行交換	`ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_SERVICE_ACCOUNT_ID` 或 `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 其中之一未設定，且沒有作用中的設定檔。	設定全部四個變數，或配置一個設定檔。
SDK 使用 API 金鑰進行驗證而非聯合	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 已設定並取得優先權。	取消設定該金鑰或權杖變數。
首次請求時出現 `FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE` 中的路徑不存在。SDK 會在交換時延遲開啟該檔案。	確認投射權杖磁碟區已掛載且路徑相符。
權杖交換成功，但 Claude API 請求傳回 403	鑄造的權杖範圍未授予對該端點的存取權限。	對照 OAuth 範圍檢查規則的 `oauth_scope`。
驗證因空憑證而失敗	憑證環境變數已匯出但設定為空字串。空值仍會佔據其優先順序位置。	使用 `unset VAR` 取消設定變數，而非 `VAR=""`。

疑難排解失敗的交換

400 invalid_grant 回應刻意保持不透明；具體原因僅記錄於伺服器端。

請先從 Claude Console 中的驗證歷史記錄頁面開始。最近的交換嘗試會顯示所評估的發行者與規則、所檢查的 JWT 宣告，以及哪個驗證步驟失敗，這通常能讓您跳過以下檢查。

如果您仍需從 JWT 本身進行除錯，請依序執行以下檢查：

解碼 JWT
解碼您傳送的 assertion，以便將每個宣告與您的發行者和規則配置進行比對：
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
檢查 iss 是否與發行者相符
解碼後的 iss 宣告必須與註冊的 issuer_url 逐位元組相等，包含協定、連接埠與任何結尾斜線。單一字元不符即會導致驗證失敗。
檢查 aud 是否與規則相符
解碼後的 aud 宣告必須包含與規則的 audience 值完全相符的內容。當 aud 為陣列時，必須有一個元素完全相符。
檢查 sub 與每個 claims 項目
將 sub 與規則的 subject_prefix 進行比對（區分大小寫；結尾的 * 為前綴比對，其他情況為完全比對）。將規則的 claims 對應中的每個鍵與同名的頂層宣告進行比對。
檢查 exp、nbf 與 iat
exp 必須在未來，nbf/iat 必須在過去，且在 30 秒偏差範圍內。如果工作負載主機的時鐘已偏移，原本有效的權杖也會被拒絕。
檢查 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 為鍵的判別聯集：

`jwks.type`	`jwks` 結構	行為	使用時機
`discovery`（預設）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base` 為選填；當探索 URL 與 `issuer_url` 不同時設定）	Anthropic 擷取 `<discovery_base or issuer_url>/.well-known/openid-configuration`，從探索文件中讀取 `jwks_uri`，並從該處擷取 JWKS。	您的 IdP 在公開網際網路上提供標準 OIDC 探索文件。大多數託管供應商（EKS、GKE、Cloud Run、GitHub Actions、Entra ID）都支援此模式。
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic 直接從 `url` 擷取 JWKS。`issuer_url` 僅用於與 JWT `iss` 宣告進行字串比對，絕不會被連線。	您的 IdP 不提供探索文件，或探索僅限內部但 JWKS 可公開存取。
`inline`	`{ "type": "inline", "keys": [...] }`	您以內嵌方式提供 JWK 物件陣列（JWKS 文件中的 `keys` 陣列，而非包裝物件）。Anthropic 不會發出任何對外請求。`issuer_url` 僅用於 `iss` 比對。	隔離環境、具有叢集內部發行者 URL 的自行管理 Kubernetes 叢集，或當您希望明確控制金鑰輪替時。

判別聯集在結構上使伴隨欄位互斥。discovery 與 explicit_url 也都接受選填的 ca_cert_pem 字串，用於從私有 CA 提供 TLS 的發行者。

金鑰輪替與快取

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

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

在 inline 模式中沒有自動金鑰重新整理。當您的身分提供者輪替其簽署金鑰時，您必須使用新的 JWKS 更新發行者配置，否則所有權杖交換都會因簽章驗證而失敗。

Was this page helpful?

管理驗證

WIF 參考

Workload Identity Federation 的環境變數、驗證規則、設定檔配置與錯誤參考。

本頁彙整了 Workload Identity Federation 的配置介面、驗證限制與錯誤對應。如需設定逐步說明，請參閱供應商指南。

權杖交換請求

欄位	必填	說明
`grant_type`	是	一律為 `urn:ietf:params:oauth:grant-type:jwt-bearer`。
`assertion`	是	由您的身分提供者核發的 OIDC JWT。
`federation_rule_id`	是	要評估之聯合規則的標記 ID（`fdrl_...`）。
`organization_id`	是	您的 Anthropic 組織的 UUID。
`service_account_id`	是	目標服務帳戶的標記 ID（`svac_...`）。
`workspace_id`	視情況而定	要將鑄造的權杖限定範圍至的工作區標記 ID（`wrkspc_...`），或使用字面值 `default` 表示組織的預設工作區。當規則啟用於多個工作區時為必填。若省略，伺服器會選取該規則唯一啟用的工作區。

權杖交換回應

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

欄位	類型	說明
`access_token`	string	短期有效的 Anthropic 權杖，前綴為 `sk-ant-oat01-...`。以 `Authorization: Bearer <token>` 的形式傳遞。
`token_type`	string	一律為 `Bearer`。
`expires_in`	integer	權杖到期前的秒數。
`scope`	string	由符合的規則所授予的 OAuth 範圍。

環境變數

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

變數	必填	說明	範例
`ANTHROPIC_FEDERATION_RULE_ID`	是	要評估之聯合規則的標記 ID。	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	是	您的 Anthropic 組織的 UUID。可在 Claude Console 的 Settings > Organization 下找到。	`00000000-0000-0000-0000-000000000000`
`ANTHROPIC_IDENTITY_TOKEN_FILE`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	由您的「identity provider」（身分提供者），即 IdP 所核發之 JWT 的檔案系統路徑。SDK 會在每次交換時重新讀取此檔案，以確保在磁碟上輪替的投射權杖始終為最新。	`/var/run/secrets/anthropic.com/token`
`ANTHROPIC_IDENTITY_TOKEN`	`_TOKEN_FILE` 或 `_TOKEN` 擇一	以字串形式提供的 JWT 字面值。當您的平台以環境變數而非檔案的方式注入權杖時使用。	`eyJhbGciOiJSUzI1NiIs...`
`ANTHROPIC_SERVICE_ACCOUNT_ID`	是	目標 Anthropic 服務帳戶的標記 ID，核發的存取權杖將以此帳戶身分運作。	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	視情況而定	要將鑄造的權杖限定範圍至的工作區標記 ID，或字面值 `default`。當聯合規則啟用於多個工作區時為必填；當規則僅繫結至單一工作區時為選填。鑄造的權杖在交換時即限定於此工作區，因此切換工作區需要進行新的交換。	`wrkspc_...`
`ANTHROPIC_PROFILE`	否	要載入的配置設定檔名稱。優先於本表中的聯合環境變數。	`staging-profile`

憑證優先順序

SDK 會依此順序解析憑證。第一個產生憑證的來源即為採用對象。

順序	來源	備註
1	建構函式引數（`api_key=`、`auth_token=`、`credentials=`）	一律覆寫其他所有來源。
2	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`	完全遮蔽聯合。從 API 金鑰遷移時請取消設定這些變數。
3	`ANTHROPIC_PROFILE`	載入 `<config_dir>/configs/<name>.json`。找不到指定名稱的設定檔會產生錯誤，而非繼續往下嘗試。
4	聯合環境變數	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`。
5	作用中設定檔	從 `<config_dir>/active_config` 解析，若無則回退至名為 `default` 的設定檔。

設定檔配置檔案

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

配置目錄

SDK 會依此順序尋找配置目錄：

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

作用中設定檔

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

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

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

檔案配置

路徑	內容	敏感性
`<config_dir>/configs/<profile>.json`	`version`、`authentication` 區塊、`organization_id`、`workspace_id` 與 `base_url`。	非機密。可安全提交或內建至映像中。
`<config_dir>/credentials/<profile>.json`	`version`、快取的 `access_token`、`expires_at`，以及（用於互動式登入的）`refresh_token`。	機密。由 SDK 以 `0600` 模式寫入。

聯合設定檔範例

configs/production.json

{
  "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 端點。

範圍	授予存取權限
`workspace:developer`	規則工作區中所有非管理性的 Claude API 端點：Messages（包含串流與權杖計數）、Models、Managed Agents 及其工作階段、Files，以及 Skills。這與為相同工作區核發的 API 金鑰所擁有的存取權限相符。
`org:manage_tunnels`	MCP 通道 API：列出與取得通道、註冊與封存 CA 憑證、顯示與輪替通道權杖，以及封存通道。當您從 Console 的建立通道對話框建立規則時，該對話框會鎖定此範圍。

對權杖範圍以外端點的請求會傳回 HTTP 403。目前不提供更細緻的範圍（按資源劃分，或讀取與寫入區分）。

驗證規則

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

資源欄位

欄位	限制
發行者、規則與服務帳戶的 `name`	必須符合 `^[a-z0-9-]+$`，長度為 1 至 255 個字元。
`workspace_id`	選填。其配額、計費與速率限制適用於依此規則鑄造之權杖的工作區（`wrkspc_...`）。必須是同一組織中的工作區，且目標服務帳戶必須是該工作區的成員。對於僅配置單一工作區的規則可省略。
`token_lifetime_seconds`	介於 `60` 與 `86400` 之間的整數（1 分鐘至 24 小時）。預設為 `3600`。超出此範圍的值會在請求時被拒絕。請參閱權杖存留期與重新整理。

URL 欄位

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

限制	詳細說明
協定	必須為 `https`。
連接埠	必須為 `443`（明確指定或預設）。
主機	必須是您的 OIDC 提供者的公開 DNS 主機名稱。必須解析為公開 IP 位址；不接受 IP 字面值。

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

JWT 驗證

限制	詳細說明
最大大小	`assertion` JWT 最多為 16 KiB。
簽署演算法	僅接受非對稱演算法（RSA 與 ECDSA 系列：ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512）。HMAC（`HS256`、`HS384`、`HS512`）與 `none` 會被拒絕。
金鑰 ID	JWT 標頭必須帶有與發行者 JWKS 中某個金鑰相符的 `kid`。沒有 `kid` 的權杖會被拒絕。
必要宣告	`sub` 必須存在。`iat` 必須存在且不在未來。`exp` 必須存在且在未來。
最大存留期	權杖的存留期（`exp` 減去 `iat`）不得超過發行者配置的最大值（預設為 1 小時，可在 Claude Console 中為每個發行者配置）。
時鐘偏差	對 `exp`、`nbf` 與 `iat` 套用 30 秒的容許範圍。

規則比對語意

比對器	類型	語意
`subject_prefix`	string	與 JWT `sub` 宣告進行完全比對。結尾的 `` 使其成為前綴比對（`sub` 值必須以 `` 之前的字元開頭）。區分大小寫。
`audience`	string	JWT `aud` 宣告必須包含此完全相符的字串。當 `aud` 為陣列時，任何完全相符的元素即滿足檢查。
`claims`	map<string, string>	每個鍵是頂層宣告名稱，每個值是所需的完全相符字串值。對於巢狀、數值、布林或如清單與對應等複雜宣告，請改用帶有 CEL 運算式的 `condition`。
`condition`	string (CEL)	必須評估為 `true` 的 CEL 運算式。

CEL 評估環境

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

變數	類型	內容
`claims`	map	完整解碼的 JWT 宣告集。巢狀物件可作為巢狀對應存取。

範例：

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

CEL 條件是安全邊界。對超出預期範圍的輸入評估為 true 的運算式，會授予超出預期的存取權限。當靜態比對器能表達您的限制時，請優先使用它們。

錯誤

權杖交換錯誤

狀態	錯誤	原因	解決方式
400	`invalid_request`	`federation_rule_id` 格式錯誤，或缺少必要的請求欄位。	驗證 `fdrl_` ID，並確認請求主體包含所有必要欄位。
400	`invalid_request`	`workspace_id_required`：聯合規則啟用於多個工作區，而請求省略了 `workspace_id`。	將 `ANTHROPIC_WORKSPACE_ID`（或原始請求中的 `workspace_id` 主體欄位）設定為您希望權杖限定範圍至的 `wrkspc_...` ID。請參閱權杖交換請求。
400	`invalid_grant`	JWT `iss` 宣告與註冊的 `issuer_url` 不完全相等。	逐位元組比對，包含結尾斜線與協定：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKS 擷取失敗、JWKS 已過時，或 JWT 使用不在 JWKS 中的金鑰簽署。	對於 `inline` 模式，請使用輪替後的金鑰更新發行者。對於 `discovery` 與 `explicit_url`，請確認 JWKS 端點可透過連接埠 443 存取；如果發行者最近輪替了其簽署金鑰，請參閱金鑰輪替與快取。
400	`invalid_grant`	JWT `exp` 宣告已過期（超出 30 秒偏差範圍）。	確認您的身分提供者正在投射新的權杖，且 SDK 正在重新讀取權杖檔案。
400	`invalid_grant`	JWT 已通過驗證，但其宣告不滿足規則的 `match` 區塊。	解碼 JWT 並將每個宣告與規則進行比對。`subject_prefix` 區分大小寫。`audience` 需要完全相符的元素比對。
400	`invalid_grant`	`federation_rule_id` 不存在、已封存，或 JWT 未獲授權使用該規則（合併處理以防止列舉）。	在 Claude Console 中確認規則 ID，並確認該規則尚未被封存。

所有 invalid_grant 失敗都會傳回 HTTP 400；具體原因僅記錄於伺服器端，不會在回應中公開。

常見的 SDK 端失敗

症狀	原因	解決方式
SDK 回報「no credentials」而非進行交換	`ANTHROPIC_FEDERATION_RULE_ID`、`ANTHROPIC_ORGANIZATION_ID`、`ANTHROPIC_SERVICE_ACCOUNT_ID` 或 `ANTHROPIC_IDENTITY_TOKEN[_FILE]` 其中之一未設定，且沒有作用中的設定檔。	設定全部四個變數，或配置一個設定檔。
SDK 使用 API 金鑰進行驗證而非聯合	`ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 已設定並取得優先權。	取消設定該金鑰或權杖變數。
首次請求時出現 `FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE` 中的路徑不存在。SDK 會在交換時延遲開啟該檔案。	確認投射權杖磁碟區已掛載且路徑相符。
權杖交換成功，但 Claude API 請求傳回 403	鑄造的權杖範圍未授予對該端點的存取權限。	對照 OAuth 範圍檢查規則的 `oauth_scope`。
驗證因空憑證而失敗	憑證環境變數已匯出但設定為空字串。空值仍會佔據其優先順序位置。	使用 `unset VAR` 取消設定變數，而非 `VAR=""`。

疑難排解失敗的交換

400 invalid_grant 回應刻意保持不透明；具體原因僅記錄於伺服器端。

如果您仍需從 JWT 本身進行除錯，請依序執行以下檢查：

解碼 JWT
解碼您傳送的 assertion，以便將每個宣告與您的發行者和規則配置進行比對：
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
檢查 iss 是否與發行者相符
解碼後的 iss 宣告必須與註冊的 issuer_url 逐位元組相等，包含協定、連接埠與任何結尾斜線。單一字元不符即會導致驗證失敗。
檢查 aud 是否與規則相符
解碼後的 aud 宣告必須包含與規則的 audience 值完全相符的內容。當 aud 為陣列時，必須有一個元素完全相符。
檢查 sub 與每個 claims 項目
將 sub 與規則的 subject_prefix 進行比對（區分大小寫；結尾的 * 為前綴比對，其他情況為完全比對）。將規則的 claims 對應中的每個鍵與同名的頂層宣告進行比對。
檢查 exp、nbf 與 iat
exp 必須在未來，nbf/iat 必須在過去，且在 30 秒偏差範圍內。如果工作負載主機的時鐘已偏移，原本有效的權杖也會被拒絕。
檢查 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 為鍵的判別聯集：

`jwks.type`	`jwks` 結構	行為	使用時機
`discovery`（預設）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base` 為選填；當探索 URL 與 `issuer_url` 不同時設定）	Anthropic 擷取 `<discovery_base or issuer_url>/.well-known/openid-configuration`，從探索文件中讀取 `jwks_uri`，並從該處擷取 JWKS。	您的 IdP 在公開網際網路上提供標準 OIDC 探索文件。大多數託管供應商（EKS、GKE、Cloud Run、GitHub Actions、Entra ID）都支援此模式。
`explicit_url`	`{ "type": "explicit_url", "url": "https://..." }`	Anthropic 直接從 `url` 擷取 JWKS。`issuer_url` 僅用於與 JWT `iss` 宣告進行字串比對，絕不會被連線。	您的 IdP 不提供探索文件，或探索僅限內部但 JWKS 可公開存取。
`inline`	`{ "type": "inline", "keys": [...] }`	您以內嵌方式提供 JWK 物件陣列（JWKS 文件中的 `keys` 陣列，而非包裝物件）。Anthropic 不會發出任何對外請求。`issuer_url` 僅用於 `iss` 比對。	隔離環境、具有叢集內部發行者 URL 的自行管理 Kubernetes 叢集，或當您希望明確控制金鑰輪替時。

判別聯集在結構上使伴隨欄位互斥。discovery 與 explicit_url 也都接受選填的 ca_cert_pem 字串，用於從私有 CA 提供 TLS 的發行者。

金鑰輪替與快取

Was this page helpful?