---
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)。

## Token 交換請求

`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`       | 視情況 | 要將鑄造的 token 範圍限定到的工作區標記 ID（`wrkspc_...`）。當規則在多個工作區中啟用時為必填。省略時，伺服器會選擇該規則唯一啟用的工作區。字面值 `default` 也可用於組織的 Default Workspace，但已被棄用；請改用該工作區的 `wrkspc_...` ID。 |

## Token 交換回應

`POST /v1/oauth/token` 會回傳標準的 OAuth 2.0 token 回應（[RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-5.1)）：

| 欄位             | 類型      | 說明                                                                                  |
| -------------- | ------- | ----------------------------------------------------------------------------------- |
| `access_token` | string  | 短期的 Anthropic token，前綴為 `sk-ant-oat01-...`。將其作為 `Authorization: Bearer <token>` 傳遞。 |
| `token_type`   | string  | 永遠為 `Bearer`。                                                                       |
| `expires_in`   | integer | token 過期前的秒數。                                                                       |
| `scope`        | string  | 由匹配規則授予的 OAuth 範圍。                                                                  |

## 環境變數

SDK 會讀取這些變數以執行聯合 token 交換，無需建構函式引數。

| 變數                              | 必填                          | 說明                                                                                                                                                                  | 範例                                     |
| ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `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` 擇一 | 由您的身分提供者（IdP）所簽發之 JWT 的檔案系統路徑。SDK 在每次交換時都會重新讀取此檔案，以確保在磁碟上輪替的投影 token 始終為最新。                                                                                         | `/var/run/secrets/anthropic.com/token` |
| `ANTHROPIC_IDENTITY_TOKEN`      | `_TOKEN_FILE` 或 `_TOKEN` 擇一 | 以字串形式提供的 JWT 字面值。當您的平台以環境變數而非檔案的方式注入 token 時使用。                                                                                                                     | `eyJhbGciOiJSUzI1NiIs...`              |
| `ANTHROPIC_SERVICE_ACCOUNT_ID`  | 是                           | 所簽發的存取 token 所代表之目標 Anthropic 服務帳戶的標記 ID。                                                                                                                           | `svac_...`                             |
| `ANTHROPIC_WORKSPACE_ID`        | 視情況                         | 要將鑄造的 token 範圍限定到的工作區標記 ID。當聯合規則在多個工作區中啟用時為必填；當規則僅綁定單一工作區時為選填。鑄造的 token 會在交換時限定於此工作區，因此切換工作區需要重新交換。字面值 `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>
  設定為空字串的變數仍會佔用其在憑證優先順序鏈中的位置。如果匯出了 `ANTHROPIC_API_KEY=""`，SDK 會選擇使用空金鑰的 API 金鑰路徑，而不是落入聯合。請取消設定未使用的憑證變數，而不是將其清空。
</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` 的設定檔。                                                                            |

載入設定檔時，環境變數會填補設定檔省略的任何欄位，但絕不會覆蓋設定檔明確設定的欄位。例如，`ANTHROPIC_WORKSPACE_ID` 只有在作用中設定檔未設定 `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` 決定了鑄造的存取 token 可以呼叫哪些 Claude API 端點。

| 範圍                         | 授予存取權                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `workspace:developer`      | 規則工作區中所有非管理性的 Claude API 端點：[Messages](https://platform.claude.com/docs/zh-TW/api/messages)（包括串流和 token 計數）、[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)（包括串流和 token 計數）、[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 憑證、顯示和輪替通道 token，以及封存通道。當您從 Console 的建立通道模態視窗建立規則時，它會鎖定此範圍。                                                                                                                                                                                                                                                                 |
| `org:admin`                | 對 [Admin API](https://platform.claude.com/docs/zh-TW/manage-claude/admin-api) 的完整存取權（組織成員、邀請、工作區、API 金鑰等）。OAuth `org:admin` token 只能建立或修改範圍限定為 `workspace:developer` 或 `workspace:inference` 的規則，且無法更新支援任何其他範圍規則的簽發者；請參閱[限制](https://platform.claude.com/docs/zh-TW/manage-claude/wif-admin-api#permissions-and-constraints)。                                                                                                                                |

對 token 範圍之外端點的請求會回傳 HTTP 403。目前無法使用更細粒度的範圍（每個資源，或讀取與寫入）。

### 權限邊界

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

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

## 驗證規則

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

如需完整的參數詳細資訊與回應結構描述，請參閱[服務帳戶 API 參考](https://platform.claude.com/docs/zh-TW/api/organization/service_accounts)、[聯合簽發者 API 參考](https://platform.claude.com/docs/zh-TW/api/organization/federation/issuers)和[聯合規則 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，否則建立時為必填。配額、計費和速率限制適用於此規則下鑄造的 token 的工作區（`wrkspc_...`）。必須是同一組織中的工作區，且目標服務帳戶必須是該工作區的成員。                                                                        |
| `applies_to_all_workspaces` | 布林值。設定為 `true` 以在組織中的每個工作區啟用規則，而不是指定一個；建立時需要此項或 `workspace_id`。                                                                                                                                     |
| `token_lifetime_seconds`    | 介於 `60` 和 `86400` 之間的整數（1 分鐘到 24 小時）。預設 `3600`。超出此範圍的值會在請求時被拒絕。請參閱 [Token 生命週期與重新整理](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` 的 token 會遭到拒絕。                                                                                                                                                |
| 必要宣告   | 必須包含 `sub`。必須包含 `iat` 且不得為未來時間。必須包含 `exp` 且必須為未來時間。                                                                                                                                                       |
| 單次使用   | 帶有 `jti` 宣告的斷言在每個簽發者下只能交換一次：以相同 `jti` 重複交換會被視為重放而遭到拒絕。簽發者的 `check_jti` 欄位（預設啟用）控制此檢查；沒有 `jti` 宣告的斷言不受此檢查約束。請參閱[聯合簽發者 API 參考](https://platform.claude.com/docs/zh-TW/api/organization/federation/issuers)。 |
| 生命週期上限 | token 的生命週期（`exp` 減去 `iat`）不得超過簽發者設定的上限（預設為 1 小時，可在 Claude Console 中針對每個簽發者設定）。                                                                                                                           |
| 時鐘偏差   | 對 `exp`、`nbf` 與 `iat` 套用 30 秒的寬限。                                                                                                                                                                         |

## 規則匹配語意

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

| 匹配器              | 類型                   | 語意                                                                          |
| ---------------- | -------------------- | --------------------------------------------------------------------------- |
| `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>

## 錯誤

### Token 交換錯誤

`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 的錯誤則不包含它。

| 狀態  | 錯誤                      | 原因                                                                       | 解決方法                                                                                                                                                                                                           |
| --- | ----------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 秒偏差視窗）。                                            | 確認您的身分提供者正在投影新的 token，且 SDK 正在重新讀取 token 檔案。                                                                                                                                                                   |
| 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` 主體欄位）設定為您希望 token 範圍限定到的 `wrkspc_...` ID。請參閱 [Token 交換請求](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` 並贏得優先順序。                                                                                        | 取消設定金鑰或 token 變數。                                                                                                  |
| 首次請求時出現 `FileNotFoundError`     | `ANTHROPIC_IDENTITY_TOKEN_FILE` 中的路徑不存在。SDK 在交換時延遲開啟檔案。                                                                                          | 確認投影 token 磁碟區已掛載且路徑相符。                                                                                            |
| Token 交換成功但 Claude API 請求回傳 403 | 鑄造的 token 範圍未授予對該端點的存取權。                                                                                                                         | 對照 [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 的工作負載（重試迴圈，或重新讀取未輪替 token 的重新整理）會在第二次交換時被拒絕。驗證歷史頁面會以原因 `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 秒偏差視窗內。如果工作負載主機的時鐘已漂移，否則有效的 token 會被拒絕。
  </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。如果您的身分提供者發布新的簽章金鑰並立即開始使用它簽署 token，則在快取重新整理期間，呈現這些 token 的交換可能會因簽章錯誤而失敗長達 1 分鐘。

為避免此視窗，請在您的身分提供者開始使用新簽章金鑰簽署 token 之前至少 15 分鐘在 JWKS 中發布它，並將被取代的金鑰保留在 JWKS 中，直到它簽署的 token 過期。託管身分提供者通常會自行遵循此紀律。如果您操作自己的簽發者（自管 Kubernetes 叢集、SPIRE OIDC 探索提供者，或具有配置輪替節奏的 Okta 自訂授權伺服器），請確認您的輪替政策在首次使用之前發布新金鑰。

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