---
title: WIF 參考資料
url: https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference
description: Workload Identity Federation 的環境變數、驗證規則、設定檔組態與錯誤參考資料。
---

本頁彙整了 [Workload Identity Federation](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation) 的組態介面、驗證限制與錯誤對應。如需設定逐步說明，請參閱[身分提供者指南](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#identity-providers)。

## 權杖交換請求

`POST /v1/oauth/token` 接受使用 [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523) `jwt-bearer` 授權類型的 JSON 主體。SDK 會根據[環境變數](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#environment-variables)為您建立此請求；各提供者指南中的 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` 也可用於組織的 Default Workspace，但已被棄用；請改用該工作區的 `wrkspc_...` ID。 |

## 權杖交換回應

`POST /v1/oauth/token` 會傳回標準的 OAuth 2.0 權杖回應（[RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-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 的 [Organization](https://platform.claude.com/settings/organization) 頁面（`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。當聯合規則在多個工作區中啟用時為必要；當規則僅綁定單一工作區時為選用。所簽發的權杖會在交換時限定於此工作區，因此切換工作區需要重新交換。字面值 `default` 也可用於 Default Workspace，但已被棄用；請改用其 `wrkspc_...` ID。      | `wrkspc_...`                           |
| `ANTHROPIC_PROFILE`             | 否                           | 要載入的[組態設定檔](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#profile-configuration-file)名稱。優先於此表中的聯合環境變數。                                    | `staging-profile`                      |

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

<Warning>
  設定為空字串的變數仍可能佔據其在憑證優先順序鏈中的位置。請取消設定未使用的憑證變數，而不是將其設為空白。
</Warning>

### 憑證優先順序

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` 的設定檔。                                                                          |

在 `ant` CLI 中，[Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) 的設定優先順序排在聯合（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>.json`     | `version`、`authentication` 區塊、`organization_id`、`workspace_id` 與 `base_url`。 | 非機密。可安全地提交或內建於映像中。      |
| `<config_dir>/credentials/<profile>.json` | `version`、快取的 `access_token`、`expires_at`，以及（互動式登入時的）`refresh_token`。        | 機密。由 SDK 以模式 `0600` 寫入。 |

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

### 聯合設定檔範例

```json 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](https://platform.claude.com/docs/zh-TW/api/messages)（包括串流與權杖計數）、[Models](https://platform.claude.com/docs/zh-TW/api/models/list)、[Managed Agents](https://platform.claude.com/docs/zh-TW/managed-agents/overview) 及其工作階段、[Files](https://platform.claude.com/docs/zh-TW/build-with-claude/files)，以及 [Skills](https://platform.claude.com/docs/zh-TW/build-with-claude/skills-guide)。這與同一工作區中工作區 API 金鑰所擁有的存取權相同。 |
| `workspace:inference`      | 規則所屬工作區中的推論端點：[Messages](https://platform.claude.com/docs/zh-TW/api/messages)（包括串流與權杖計數）、[Models](https://platform.claude.com/docs/zh-TW/api/models/list)，以及 [OpenAI 相容聊天端點](https://platform.claude.com/docs/zh-TW/cli-sdks-libraries/libraries/openai-sdk)。適用於只需呼叫 Claude、永遠不需要管理 Files、Skills 或其他資源的工作負載。                                                                                                                                              |
| `workspace:manage_tunnels` | [MCP tunnels API](https://platform.claude.com/docs/zh-TW/agents-and-tools/mcp-tunnels/reference#tunnels-api)：建立、列出與取得通道，註冊與封存 CA 憑證，顯示與輪替通道權杖，以及封存通道。當您從 Console 的建立通道對話視窗建立規則時，該視窗會鎖定此範圍。                                                                                                                                                                                                                                                                |
| `org:admin`                | 完整存取 [Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api)（組織成員、邀請、工作區、API 金鑰等）。OAuth `org:admin` 權杖只能建立或修改範圍為 `workspace:developer` 或 `workspace:inference` 的規則，且無法更新支援任何其他範圍規則的簽發者；請參閱[限制](https://platform.claude.com/docs/zh-TW/manage-claude/wif-admin-api#permissions-and-constraints)。                                                                                                                                       |

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

### 權限邊界

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

| 規則 `oauth_scope`      | 服務帳戶 `organization_role` | 有效權限                                                                                                                                                               |
| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspace:developer` | `admin`                  | 僅限規則所屬工作區中的 Claude API 存取權。範圍將權杖限制在角色之下。                                                                                                                           |
| `org:admin`           | `admin`                  | 完整的 Admin API 存取權（組織成員、邀請、工作區、API 金鑰等），但扣除 OAuth 呼叫者的例外限制；請參閱[限制](https://platform.claude.com/docs/zh-TW/manage-claude/wif-admin-api#permissions-and-constraints)。 |

## 驗證規則

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

如需完整的參數詳細資訊與回應結構描述，請參閱 [Service accounts API 參考資料](https://platform.claude.com/docs/zh-TW/api/organization/service_accounts)、[Federation issuers API 參考資料](https://platform.claude.com/docs/zh-TW/api/organization/federation/issuers)與 [Federation rules API 參考資料](https://platform.claude.com/docs/zh-TW/api/organization/federation/rules)。

### 資源欄位

| 欄位                          | 限制                                                                                                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 簽發者、規則與服務帳戶的 `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`。超出此範圍的值會在請求時被拒絕。請參閱[權杖有效期與重新整理](https://platform.claude.com/docs/zh-TW/manage-claude/workload-identity-federation#token-lifetime-and-refresh)。 |

### 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`）。

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

### 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` 且必須為未來時間。                                                                                                                                                                      |
| 單次使用  | 帶有 `jti` 宣告的斷言在每個簽發者下只能交換一次：以相同 `jti` 重複交換會被視為重放而遭拒絕。簽發者的 `check_jti` 欄位（預設啟用）控制此檢查；沒有 `jti` 宣告的斷言不受此檢查約束。請參閱 [Federation issuers API 參考資料](https://platform.claude.com/docs/zh-TW/api/organization/federation/issuers)。 |
| 有效期上限 | 權杖的有效期（`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](https://cel.dev/) 運算式。                               |

### CEL 評估環境

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

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

範例：

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

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

## 錯誤

### 權杖交換錯誤

`POST /v1/oauth/token` 以標準的 [API 錯誤格式](https://platform.claude.com/docs/zh-TW/api/errors)傳回錯誤。SDK 會將交換失敗回報為 `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`)，其中提供 HTTP 狀態以及回應主體中的錯誤詳細資訊。在 Python、TypeScript 與 Ruby 中，請求 ID 位於錯誤物件上；在 Java 中則位於例外的回應標頭中。在 Go 中，它只出現在錯誤訊息中，因為錯誤的類型位於內部套件；C# 與 PHP 的錯誤則不包含請求 ID。

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

每次斷言遭拒都會傳回相同的不透明 `401` `authentication_error`，並帶有固定訊息 `Authentication failed`，無論是哪項檢查失敗；可區分的錯誤會讓呼叫者得以探測規則組態。拒絕原因會記錄在 Claude Console 中[驗證歷程記錄](https://platform.claude.com/settings/workload-identity-federation?tab=history)的該次嘗試項目上，例如當 `sub` 宣告不符合規則的 `subject_prefix` 時為 `match_subject_prefix`，或當規則跨越多個工作區而請求未指定任何工作區時為 `workspace_id_required`。在確認規則所屬組織之前就被拒絕的請求（上述 `400 invalid_request_error` 類別）不會留下歷程記錄項目；其回應訊息會直接指出問題。沒有對應歷程記錄項目的 `401` 通常表示 `federation_rule_id` 本身無法辨識。

### 常見的 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 範圍](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#oauth-scopes)檢查規則的 `oauth_scope`。 |
| 驗證因空白憑證而失敗                   | 某個憑證環境變數已匯出但設為空字串。空值可能仍會贏得其優先順序位置。                                                                                                                | 使用 `unset VAR` 取消設定變數，而不是 `VAR=""`。                                                                                |

## 疑難排解失敗的交換

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

<Tip>
  請從 Claude Console 中的[驗證歷程記錄頁面](https://platform.claude.com/settings/workload-identity-federation?tab=history)開始。最近的交換嘗試會顯示所評估的簽發者與規則、所檢查的 JWT 宣告，以及哪個驗證步驟失敗，這通常能讓您省略以下的檢查。
</Tip>

一種常見的不透明失敗是重放的斷言：帶有 `jti` 宣告的斷言[只能交換一次](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#jwt-verification)，因此重新傳送相同 JWT 的工作負載（重試迴圈，或重新讀取未輪替權杖的重新整理）會在第二次交換時遭拒。驗證歷程記錄頁面會以原因 `jti_reused` 顯示這些嘗試；修正方式是為每次交換簽發新的斷言。

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

<Steps>
  <Step title="解碼 JWT">
    解碼您傳送的斷言，以便將每個宣告與您的簽發者和規則組態進行比對：

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

  <Step title="檢查 iss 是否與簽發者相符">
    解碼後的 `iss` 宣告必須與註冊的 `issuer_url` 逐位元組相同，包括協定、連接埠以及任何結尾斜線。即使只有一個字元不符也會導致驗證失敗。
  </Step>

  <Step title="檢查 aud 是否與規則相符">
    解碼後的 `aud` 宣告必須包含與規則 `audience` 值完全相符的內容。當 `aud` 為陣列時，必須有一個元素完全相符。
  </Step>

  <Step title="檢查 sub 與每個 claims 項目">
    將 `sub` 與規則的 `subject_prefix` 比對（區分大小寫；結尾的 `*` 為前綴比對，其他情況則為完全比對）。將規則 `claims` 對應中的每個鍵與同名的頂層宣告比對。
  </Step>

  <Step title="檢查 exp、nbf 與 iat">
    `exp` 必須為未來時間，`nbf`/`iat` 必須為過去時間，並在 30 秒偏差範圍內。如果工作負載主機的時鐘發生漂移，原本有效的權杖也會被拒絕。
  </Step>

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

    如果簽發者輪替了簽署金鑰並立即開始使用它簽署，在 Anthropic 的 JWKS 快取重新整理期間，交換可能會失敗長達一分鐘。請參閱[金鑰輪替與快取](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#key-rotation-and-caching)。
  </Step>
</Steps>

## 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。如果您的身分提供者發佈新的簽署金鑰並立即開始用它簽署權杖，在快取重新整理期間，出示這些權杖的交換可能會因簽章錯誤而失敗長達 1 分鐘。

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

<Warning>
  在 `inline` 模式中沒有自動金鑰重新整理。當您的身分提供者輪替其簽署金鑰時，您必須以新的 JWKS 更新簽發者組態，否則所有權杖交換都會在簽章驗證時失敗。
</Warning>