Claude Platform Docs
管理驗證

WIF 參考資料

工作負載身分聯合的環境變數、驗證規則、設定檔組態與錯誤參考資料。

本頁彙整了工作負載身分聯合(WIF)的組態介面、驗證限制與錯誤對應。如需設定逐步說明,請參閱身分提供者。

權杖交換請求

POST /v1/oauth/token 接受使用 RFC 7523 jwt-bearer 授權類型的 JSON 主體。SDK 會根據環境變數為您建立此請求。

欄位必要說明
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 也可用於組織的預設工作區,但已被棄用。請改用該工作區的 wrkspc_... ID。

權杖交換回應

POST /v1/oauth/token 會傳回標準的 OAuth 2.0 權杖回應(RFC 6749 §5.1):

欄位類型說明
access_tokenstring短期有效的 Anthropic 權杖,前綴為 sk-ant-oat01-...。請以 Authorization: Bearer <token> 的形式傳遞。
token_typestring一律為 Bearer。
expires_ininteger距離權杖到期的秒數。
scopestring由相符規則授予的 OAuth 範圍。

環境變數

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

變數必要說明範例
ANTHROPIC_FEDERATION_RULE_ID是要評估的聯合規則的標記 ID。fdrl_...
ANTHROPIC_ORGANIZATION_ID是您的 Anthropic 組織的 UUID。可在 Claude Console 的組織頁面(platform.claude.com/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。當聯合規則在多個工作區中啟用時為必要。當規則僅綁定單一工作區時為選用。交換會將所簽發的權杖限定於此工作區,因此切換工作區需要重新交換。若未使用設定檔,ant CLI 不會將此變數傳入交換。使用 ant CLI 時,請在聯合設定檔中設定 workspace_id,並將 ANTHROPIC_PROFILE 設為該設定檔的名稱。字面值 default 也可用於預設工作區,但已被棄用。請改用其 wrkspc_... ID。wrkspc_...
ANTHROPIC_PROFILE否要載入的組態設定檔名稱。優先於此表中的聯合環境變數。staging-profile

只有在 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID,以及 ANTHROPIC_IDENTITY_TOKEN_FILE 或 ANTHROPIC_IDENTITY_TOKEN 其中之一全部設定時,直接環境變數聯合路徑才會啟用。SDK 也會讀取 ANTHROPIC_WORKSPACE_ID,但無論是否設定它,此路徑都會啟用。

憑證優先順序

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

順序來源備註
1建構函式引數(API 金鑰、驗證權杖或憑證)一律覆寫其他所有來源。
2ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN完全覆寫聯合。從 API 金鑰遷移時請取消設定這些變數。
3ANTHROPIC_PROFILE載入 <config_dir>/configs/<name>.json。如果找不到指定名稱的設定檔,SDK 會回報錯誤,而不會嘗試下一個來源。
4聯合環境變數ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID + ANTHROPIC_SERVICE_ACCOUNT_ID + ANTHROPIC_IDENTITY_TOKEN[_FILE]。
5作用中設定檔從 <config_dir>/active_config 解析,若無則退回名為 default 的設定檔。

在 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 遵循相同的解析順序,因此在此設定的聯合設定檔也能為這些工具進行驗證,無需額外設定。

檔案配置

路徑內容敏感性
<config_dir>/configs/<profile>.jsonversion、authentication 區塊、organization_id、workspace_id 與 base_url。非機密。可安全地提交或內建於映像中。
<config_dir>/credentials/<profile>.jsonversion、快取的 access_token、expires_at,以及(互動式登入時的)refresh_token。機密。SDK 會以模式 0600 寫入此檔案。

組態檔案與憑證檔案都帶有一個頂層字串 version 欄位,格式為 major.minor,例如 "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可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。、Managed Agents 及其工作階段、Files,以及 Skills。這與同一工作區中工作區 API 金鑰所擁有的存取權相同。
workspace:inference規則所屬工作區中的推論端點:Messages(包括串流與權杖計數)、Models可檢視預覽,內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片,按 Escape 鍵返回。,以及 OpenAI 相容聊天端點。適用於只需呼叫 Claude、永遠不需要管理 Files、Skills 或其他資源的工作負載。
workspace:manage_tunnelsMCP 通道 API:建立、列出與取得通道,註冊與封存 CA 憑證,顯示與輪替通道權杖,以及封存通道。當您從 Console 的建立通道對話視窗建立規則時,該視窗會鎖定此範圍。
org:admin對 Admin API 的完整存取權(組織成員、邀請、工作區、API 金鑰等)。OAuth org:admin 權杖只能建立或修改範圍為 workspace:developer 或 workspace:inference 的規則。它無法更新支援任何其他範圍規則的簽發者。請參閱權限與限制。

對權杖範圍之外的端點發出請求會傳回 HTTP 403。目前不提供更細緻的範圍(依資源或讀取與寫入區分)。

權限邊界

聯合規則的 oauth_scope 是上限:所簽發的權杖永遠不會超過它。目標服務帳戶的 organization_role(developer 或 admin)決定了規則可授予哪些範圍。授予 org:admin 的規則必須以 organization_role=admin 的服務帳戶為目標。有效權限是規則範圍與服務帳戶角色的交集。

規則 oauth_scope服務帳戶 organization_role有效權限
workspace:developeradmin僅限規則所屬工作區中的 Claude API 存取權。範圍將權杖限制在角色之下。
org:adminadmin完整的 Admin API 存取權(組織成員、邀請、工作區、API 金鑰等),扣除 OAuth 呼叫者的例外情況。請參閱權限與限制。

驗證規則

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

如需完整的參數詳細資訊與回應結構描述,請參閱服務帳戶 API 參考資料、聯合簽發者 API 參考資料與聯合規則 API 參考資料。

資源欄位

欄位限制
簽發者、規則與服務帳戶的 name必須符合 ^[a-z0-9-]+$,長度為 1 到 255 個字元。
workspace_id建立時為必要,除非 applies_to_all_workspaces 為 true。其配額、計費與速率限制適用於此規則下所簽發權杖的工作區(wrkspc_...)。必須是同一組織中的工作區,且目標服務帳戶必須是該工作區的成員。
applies_to_all_workspaces布林值。設為 true 可在組織中的每個工作區啟用此規則,而不必指定單一工作區。建立時必須提供此欄位或 workspace_id 其中之一。
token_lifetime_seconds介於 60 與 86400 之間的整數(1 分鐘到 24 小時)。預設為 3600。Anthropic 會在請求時拒絕超出此範圍的值。請參閱權杖存留時間與重新整理。

URL 欄位

Anthropic 會驗證 issuer_url、jwks.discovery_base 與 jwks.url 欄位:

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

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

JWT 驗證

限制詳細資訊
大小上限assertion JWT 最多為 16 KiB。
簽章演算法Anthropic 僅接受非對稱演算法(RSA 與 ECDSA 系列:ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512)。它會拒絕 HMAC(HS256、HS384、HS512)與 none。
金鑰 IDJWT 標頭必須帶有與簽發者 JWKS 中某個金鑰相符的 kid。Anthropic 會拒絕沒有 kid 的權杖。
必要宣告必須包含 sub。必須包含 iat 且不得為未來時間。必須包含 exp 且必須為未來時間。
單次使用帶有 jti 宣告的斷言在每個簽發者下只能交換一次。Anthropic 會將以相同 jti 重複進行的交換視為重放而拒絕。簽發者的 check_jti 欄位(預設啟用)控制此檢查。沒有 jti 宣告的斷言不受此檢查約束。請參閱聯合簽發者 API 參考資料。
有效期上限權杖的有效期(exp 減去 iat)不得超過簽發者設定的上限(預設為 1 小時,可在 Claude Console 中為每個簽發者設定)。
時鐘偏差Anthropic 對 exp、nbf 與 iat 套用 30 秒的寬限。

規則比對語意

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

比對器類型語意
subject_prefixstring與 JWT sub 宣告進行完全比對。結尾的 * 會使其成為前綴比對(sub 值必須以 * 之前的字元開頭)。區分大小寫。
audiencestringJWT aud 宣告必須包含此確切字串。當 aud 為陣列時,任一元素完全相符即滿足檢查。
claimsmap<string, string>每個鍵是一個頂層宣告名稱,每個值是必須完全相符的字串值。對於巢狀、數值、布林或複雜宣告(例如清單與對應),請改用搭配「Common Expression Language」(通用運算式語言),即 CEL,運算式的 condition。
conditionstring (CEL)必須評估為 true 的 CEL 運算式。

CEL 評估環境

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

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

範例:

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

錯誤

權杖交換錯誤

POST /v1/oauth/token 以標準的 API 錯誤格式傳回錯誤。SDK 會將交換失敗回報為 WorkloadIdentityError,其中提供 HTTP 狀態以及回應主體中的錯誤詳細資訊。除了 C# 與 PHP 之外,SDK 也會提供請求 ID:放在錯誤物件上、例外的回應標頭中,或錯誤訊息中。

狀態錯誤原因解決方式
400invalid_request_errorfederation_rule_id 格式錯誤,或缺少必要的請求欄位。檢查 fdrl_ ID,並確認請求主體包含所有必要欄位。
400invalid_request_error提供了 workspace_id,但它不是格式正確的 wrkspc_... ID 或字面值 default。修正 workspace_id 值。回應訊息會指出預期的格式。
401authentication_errorJWT iss 宣告與註冊的 issuer_url 不完全相同。逐位元組比對,包括結尾斜線與協定:jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson | .iss' <<< "$JWT"。
401authentication_errorJWKS 擷取失敗、JWKS 已過時,或 JWT 是以不在 JWKS 中的金鑰簽署。對於 inline 模式,請以輪替後的金鑰更新簽發者。對於 discovery 與 explicit_url,請確認 JWKS 端點可透過連接埠 443 連線。如果簽發者最近輪替了簽署金鑰,請參閱金鑰輪替與快取。
401authentication_errorJWT exp 宣告已是過去時間(超出 30 秒偏差範圍)。確認您的身分提供者正在投射新的權杖,且 SDK 正在重新讀取權杖檔案。
401authentication_errorJWT 已通過驗證,但其宣告不符合規則的 match 區塊。解碼 JWT 並將每個宣告與規則比對。subject_prefix 區分大小寫。audience 需要元素完全相符。
401authentication_errorfederation_rule_id 不存在或已封存,或 JWT 未獲授權使用該規則(以單一錯誤涵蓋這些情況以防止列舉)。在 Claude Console 中確認規則 ID,並確認該規則未被封存。
401authentication_error聯合規則在多個工作區中啟用,但請求省略了 workspace_id。驗證歷程記錄項目會顯示原因 workspace_id_required。將 ANTHROPIC_WORKSPACE_ID(或原始請求中的 workspace_id 主體欄位)設為您希望權杖限定範圍的 wrkspc_... ID。使用 ant CLI 時,請在聯合設定檔中設定 workspace_id,並將 ANTHROPIC_PROFILE 設為該設定檔的名稱。請參閱權杖交換請求。

每次斷言遭拒都會傳回相同的不透明 401 authentication_error,並帶有固定訊息 Authentication failed,無論是哪項檢查失敗。可區分的錯誤會讓呼叫者得以探測規則組態。Claude Console 中的驗證歷程記錄會在該次嘗試的項目上記錄拒絕原因。例如,當 sub 宣告不符合規則的 subject_prefix 時會顯示 match_subject_prefix,或當規則跨越多個工作區而請求未指定任何工作區時會顯示 workspace_id_required。在確認規則所屬組織之前就遭拒絕的請求(上表中的 400 invalid_request_error 類別)不會留下歷程記錄項目。這些請求的回應訊息會直接指出問題。沒有對應歷程記錄項目的 401 通常表示 Anthropic 無法識別 federation_rule_id。

常見的 SDK 端失敗

症狀原因解決方式
SDK 回報缺少憑證而未進行交換ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID 或 ANTHROPIC_IDENTITY_TOKEN[_FILE] 其中之一未設定,且沒有作用中的設定檔。設定全部四個變數,或設定一個設定檔。
SDK 使用 API 金鑰驗證而非聯合已設定 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN,且其優先順序勝出。取消設定金鑰或權杖變數。
第一次請求時出現找不到檔案的錯誤ANTHROPIC_IDENTITY_TOKEN_FILE 中的路徑不存在。SDK 會在交換時才延遲開啟該檔案。確認投射權杖磁碟區已掛載且路徑相符。
權杖交換成功,但 Claude API 請求傳回 403所簽發權杖的範圍未授予該端點的存取權。對照 OAuth 範圍檢查規則的 oauth_scope。
驗證因空白憑證而失敗某個憑證環境變數已匯出但設為空字串。空值可能會贏得其優先順序位置。使用 unset VAR 取消設定變數,而不是 VAR=""。

疑難排解失敗的交換

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

一種常見的不透明失敗是重放的斷言。帶有 jti 宣告的斷言只能交換一次。重新傳送相同 JWT 的工作負載(重試迴圈,或重新讀取未輪替權杖的重新整理)會在第二次交換時失敗。驗證歷程記錄頁面會以原因 jti_reused 顯示這些嘗試。若要修正此問題,請為每次交換簽發新的斷言。

如果您需要從 JWT 本身進行偵錯,請依序執行以下檢查:

  1. 解碼 JWT

    解碼您傳送的斷言,以便將每個宣告與您的簽發者和規則組態進行比對:

    jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
  2. 檢查 iss 是否與簽發者相符

    解碼後的 iss 宣告必須與註冊的 issuer_url 逐位元組相同,包括協定、連接埠以及任何結尾斜線。即使只有一個字元不符也會導致驗證失敗。

  3. 檢查 aud 是否與規則相符

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

  4. 檢查 sub 與每個 claims 項目

    將 sub 與規則的 subject_prefix 進行比對。此比對區分大小寫。結尾的 * 會使其成為前綴比對,其他情況則為完全比對。將規則 claims 對應中的每個鍵與同名的頂層宣告進行比對。

  5. 檢查 exp、nbf 與 iat

    exp 必須為未來時間,nbf/iat 必須為過去時間,並在 30 秒偏差範圍內。如果工作負載主機的時鐘發生漂移,Anthropic 會拒絕原本有效的權杖。

  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 欄位會選擇來源模式:

jwks.typejwks 結構行為使用時機
discovery(預設){ "type": "discovery", "discovery_base": "https://..." }(當探索 URL 與 issuer_url 不同時,請設定選用的 discovery_base)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。Anthropic 僅將 issuer_url 用於與 JWT iss 宣告進行字串比對,永遠不會連線至該 URL。您的 IdP 不提供探索文件,或探索僅限內部使用但 JWKS 可公開存取。
inline{ "type": "inline", "keys": [...] }您以內嵌方式提供 JWK 物件陣列(JWKS 文件中的 keys 陣列,而非外層包裝物件)。Anthropic 不會發出任何對外請求。Anthropic 僅將 issuer_url 用於 iss 比對。隔離網路環境、使用叢集內部簽發者 URL 的自行管理 Kubernetes 叢集,或當您希望明確控制金鑰輪替時。

每個 type 都採用各自的伴隨欄位,因此這些欄位互斥。discovery 與 explicit_url 也都接受選用的 ca_cert_pem 字串,適用於從私有 CA 提供 TLS 的簽發者。

金鑰輪替與快取

在 discovery 與 explicit_url 模式中,Anthropic 會快取所擷取的 JWKS。在您的身分提供者發布新的簽署金鑰後,在快取重新整理期間,以該金鑰簽署的權杖進行交換時可能會因簽章錯誤而失敗長達 1 分鐘。

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

這個頁面有幫助嗎?