--- title: WIFリファレンス url: https://platform.claude.com/docs/ja/manage-claude/wif-reference description: Workload Identity Federationの環境変数、検証ルール、プロファイル設定、およびエラーリファレンス。 --- このページでは、[Workload Identity Federation](https://platform.claude.com/docs/ja/manage-claude/workload-identity-federation)の設定項目、検証制約、およびエラーの対応関係をまとめています。セットアップ手順については、[プロバイダーガイド](https://platform.claude.com/docs/ja/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/ja/manage-claude/wif-reference#environment-variables)からこのリクエストを自動的に構築します。各プロバイダーガイドのcURLの例では、生のボディを示しています。 | フィールド | 必須 | 説明 | | -------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | はい | 常に`urn:ietf:params:oauth:grant-type:jwt-bearer`です。 | | `assertion` | はい | IDプロバイダーが発行した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_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`のいずれか | IDプロバイダー（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/ja/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`も併せて読み取られますが、有効化の条件にはなりません。 空文字列に設定された変数でも、認証情報の優先順位チェーンにおける自身の位置を占有する場合があります。使用しない認証情報の変数は、空にするのではなく設定を解除してください。 ### 認証情報の優先順位 SDKは次の順序で認証情報を解決します。最初に認証情報を得られたソースが採用されます。 | 順序 | ソース | 注記 | | -- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | 1 | コンストラクター引数（`api_key=`、`auth_token=`、`credentials=`） | 常に他のすべてを上書きします。 | | 2 | `ANTHROPIC_API_KEY`または`ANTHROPIC_AUTH_TOKEN` | フェデレーションを完全に覆い隠します。APIキーから移行する際は、これらの設定を解除してください。 | | 3 | `ANTHROPIC_PROFILE` | `/configs/.json`を読み込みます。指定された名前のプロファイルが存在しない場合はエラーとなり、フォールスルーしません。 | | 4 | フェデレーション環境変数 | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`。 | | 5 | アクティブなプロファイル | `/active_config`から解決され、見つからない場合は`default`という名前のプロファイルにフォールバックします。 | `ant` CLIでは、[Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication)の設定の優先順位は、フェデレーション環境変数より低く、アクティブなプロファイルより高くなります。設定とは、プロジェクト、ワークスペースID、およびロケーションです。これらは`--google-cloud-*`フラグまたは`ANTHROPIC_GOOGLE_CLOUD_*`変数で設定します。CLIは、これらの設定のいずれか1つでも設定されている場合にこれらの設定を使用します。これらの設定を使用すると、CLIはGoogle Application Default Credentialsから資格情報を取得します。 プロファイルが読み込まれると、環境変数はプロファイルで省略されているフィールドを補完しますが、プロファイルで明示的に設定されたフィールドを上書きすることはありません。たとえば、`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. `/active_config`の内容（`ant profile activate `によって書き込まれる1行のファイル） 3. リテラル名`default` Claude CodeとClaude Agent SDKも同じ解決順序に従うため、ここで設定したフェデレーションプロファイルは、追加のセットアップなしでこれらのツールの認証にも使用されます。 ### ファイル構成 | パス | 内容 | 機密性 | | ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ | | `/configs/.json` | `version`、`authentication`ブロック、`organization_id`、`workspace_id`、および`base_url`。 | 非機密。コミットしたりイメージに組み込んだりしても安全です。 | | `/credentials/.json` | `version`、キャッシュされた`access_token`、`expires_at`、および（対話型ログインの場合）`refresh_token`。 | 機密。SDKによってモード`0600`で書き込まれます。 | 設定ファイルと認証情報ファイルはどちらも、`major.minor`形式（現在は`"1.0"`）のトップレベルの文字列フィールド`version`を持ちます。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/ja/api/messages)（ストリーミングとトークンカウントを含む）、[Models](https://platform.claude.com/docs/ja/api/models/list)、[Managed Agents](https://platform.claude.com/docs/ja/managed-agents/overview)とそのセッション、[Files](https://platform.claude.com/docs/ja/build-with-claude/files)、および[Skills](https://platform.claude.com/docs/ja/build-with-claude/skills-guide)。これは同じワークスペースのワークスペースAPIキーが持つアクセス権と同等です。 | | `workspace:inference` | ルールのワークスペース内の推論エンドポイント：[Messages](https://platform.claude.com/docs/ja/api/messages)（ストリーミングとトークンカウントを含む）、[Models](https://platform.claude.com/docs/ja/api/models/list)、および[OpenAI互換のチャットエンドポイント](https://platform.claude.com/docs/ja/cli-sdks-libraries/libraries/openai-sdk)。Claudeを呼び出すだけで、Files、Skills、その他のリソースを管理する必要がないワークロードに使用します。 | | `workspace:manage_tunnels` | [MCPトンネルAPI](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/reference#tunnels-api)：トンネルの作成、一覧表示、取得、CA証明書の登録とアーカイブ、トンネルトークンの表示とローテーション、およびトンネルのアーカイブ。Consoleのトンネル作成モーダルウィンドウからルールを作成すると、このスコープに固定されます。 | | `org:admin` | [Admin API](https://platform.claude.com/docs/ja/manage-claude/admin-api)（組織メンバー、招待、ワークスペース、APIキーなど）へのフルアクセス。OAuthの`org:admin`トークンは、`workspace:developer`または`workspace:inference`にスコープされたルールのみを作成または変更でき、それ以外のスコープを持つルールの基盤となっているイシュアーを更新することはできません。[制約](https://platform.claude.com/docs/ja/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/ja/manage-claude/wif-admin-api#permissions-and-constraints)を参照してください。 | ## 検証ルール Anthropicは、イシュアーとルールの作成時または更新時、および交換時に受信したJWTを検証する際に、これらの制約を適用します。 パラメーターの詳細とレスポンススキーマの全体については、[Service accounts APIリファレンス](https://platform.claude.com/docs/ja/api/organization/service_accounts)、[Federation issuers APIリファレンス](https://platform.claude.com/docs/ja/api/organization/federation/issuers)、および[Federation rules APIリファレンス](https://platform.claude.com/docs/ja/api/organization/federation/rules)を参照してください。 ### リソースフィールド | フィールド | 制約 | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | イシュアー、ルール、およびサービスアカウントの`name` | `^[a-z0-9-]+$`に一致し、長さが1〜255文字である必要があります。 | | `workspace_id` | `applies_to_all_workspaces`がtrueでない限り、作成時に必須です。このルールの下で発行されたトークンに、クォータ、請求、およびレート制限が適用されるワークスペース（`wrkspc_...`）です。同じ組織内のワークスペースである必要があり、対象サービスアカウントはそのワークスペースのメンバーである必要があります。 | | `applies_to_all_workspaces` | ブール値。1つのワークスペースを指定する代わりに、組織内のすべてのワークスペースでルールを有効にするには`true`に設定します。作成時には、これか`workspace_id`のいずれかが必須です。 | | `token_lifetime_seconds` | `60`から`86400`までの整数（1分〜24時間）。デフォルトは`3600`です。この範囲外の値はリクエスト時に拒否されます。[トークンの有効期間と更新](https://platform.claude.com/docs/ja/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`）。 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`が存在し、未来の時刻である必要があります。 | | 1回限りの使用 | `jti`クレームを持つアサーションは、イシュアーごとに1回しか交換できません。同じ`jti`で交換を繰り返すと、リプレイとして拒否されます。イシュアーの`check_jti`フィールド（デフォルトで有効）がこのチェックを制御します。`jti`クレームのないアサーションはこのチェックの対象外です。[Federation issuers APIリファレンス](https://platform.claude.com/docs/ja/api/organization/federation/issuers)を参照してください。 | | 最大有効期間 | トークンの有効期間（`exp`から`iat`を引いた値）は、イシュアーに設定された最大値（デフォルトは1時間で、Claude Consoleでイシュアーごとに設定可能）を超えてはなりません。 | | クロックスキュー | `exp`、`nbf`、および`iat`には30秒の猶予が適用されます。 | ## ルールマッチングのセマンティクス フェデレーションルールの`match`ブロックによって、受信したJWTが受け入れられるかどうかが決まります。値が設定されたすべてのフィールドはANDセマンティクスで評価され、JWTは値が設定されたすべてのマッチャーを満たす必要があります。`subject_prefix`、`claims`、または`condition`のうち少なくとも1つを設定する必要があり、`audience`のみを含む（またはマッチャーをまったく含まない）`match`ブロックは拒否されます。これにより、イシュアーからのすべてのトークンを受け入れてしまうルールを防ぎます。 | マッチャー | 型 | セマンティクス | | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | JWTの`sub`クレームとの完全一致です。末尾に`*`を付けるとプレフィックス一致になります（`sub`の値は`*`より前の文字で始まる必要があります）。大文字と小文字を区別します。 | | `audience` | string | JWTの`aud`クレームにこの文字列が完全一致で含まれている必要があります。`aud`が配列の場合、いずれかの要素が完全一致すればチェックを満たします。 | | `claims` | map\ | 各キーはトップレベルのクレーム名で、各値は必要とされる完全一致の文字列値です。ネストされたクレーム、数値、ブール値、またはリストやマップのような複雑なクレームには、代わりに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"] ``` CEL条件はセキュリティ境界です。意図したよりも多くの入力に対して`true`と評価される式は、意図したよりも広いアクセスを許可してしまいます。制約を静的マッチャーで表現できる場合は、そちらを優先してください。 ## エラー ### トークン交換エラー `POST /v1/oauth/token`は、標準の[APIエラー形式](https://platform.claude.com/docs/ja/api/errors)でエラーを返します。SDKは交換の失敗を`WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`)として報告し、HTTPステータスとレスポンスボディのエラー詳細を提供します。リクエストIDは、Python、TypeScript、Rubyではエラー上に、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/ja/manage-claude/wif-reference#key-rotation-and-caching)を参照してください。 | | 401 | `authentication_error` | JWTの`exp`クレームが過去の時刻です（30秒のスキュー範囲を超えています）。 | IDプロバイダーが新しいトークンを投影していること、および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/ja/manage-claude/wif-reference#token-exchange-request)を参照してください。 | アサーションが拒否された場合は、どのチェックに失敗したかにかかわらず、固定メッセージ`Authentication failed`を持つ同一の不透明な`401` `authentication_error`が返されます。区別可能なエラーを返すと、呼び出し元がルール設定を探ることができてしまうためです。拒否理由は、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]`のいずれかが設定されておらず、アクティブなプロファイルもありません。 | 4つの変数をすべて設定するか、プロファイルを設定してください。 | | SDKがフェデレーションではなくAPIキーで認証する | `ANTHROPIC_API_KEY`または`ANTHROPIC_AUTH_TOKEN`が設定されており、優先されています。 | キーまたはトークンの変数の設定を解除してください。 | | 最初のリクエストで`FileNotFoundError`が発生する | `ANTHROPIC_IDENTITY_TOKEN_FILE`のパスが存在しません。SDKは交換時に遅延してファイルを開きます。 | 投影トークンのボリュームがマウントされており、パスが一致していることを確認してください。 | | トークン交換は成功するが、Claude APIリクエストが403を返す | 発行されたトークンのスコープが、そのエンドポイントへのアクセスを許可していません。 | ルールの`oauth_scope`を[OAuthスコープ](https://platform.claude.com/docs/ja/manage-claude/wif-reference#oauth-scopes)と照らし合わせて確認してください。 | | 空の認証情報で認証が失敗する | 認証情報の環境変数がエクスポートされていますが、空文字列に設定されています。空の値でも優先順位の位置を獲得する場合があります。 | `VAR=""`ではなく`unset VAR`で変数の設定を解除してください。 | ## 失敗した交換のトラブルシューティング `401` `authentication_error`レスポンスは意図的に不透明になっており、そのメッセージは常に`Authentication failed`です。拒否理由はレスポンスではなく、認証履歴に記録されます。 まずClaude Consoleの[認証履歴ページ](https://platform.claude.com/settings/workload-identity-federation?tab=history)から始めてください。最近の交換試行では、評価されたイシュアーとルール、検査されたJWTクレーム、およびどの検証ステップで失敗したかが表示されるため、通常は以下のチェックを省略できます。 よくある不透明な失敗の1つは、リプレイされたアサーションです。`jti`クレームを持つアサーションは[1回しか交換できない](https://platform.claude.com/docs/ja/manage-claude/wif-reference#jwt-verification)ため、同じJWTを再送信するワークロード（リトライループや、ローテーションされていないトークンを再読み込みする更新処理）は、2回目の交換で拒否されます。認証履歴ページでは、これらの試行が理由`jti_reused`とともに表示されます。修正方法は、交換ごとに新しいアサーションを発行することです。 それでもJWT自体からデバッグする必要がある場合は、次のチェックを順番に行ってください。 送信したアサーションをデコードし、各クレームをイシュアーとルールの設定と比較できるようにします。 ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` デコードされた`iss`クレームは、スキーム、ポート、および末尾のスラッシュを含め、登録された`issuer_url`とバイト単位で一致する必要があります。1文字でも不一致があると検証に失敗します。 デコードされた`aud`クレームには、ルールの`audience`の値が完全一致で含まれている必要があります。`aud`が配列の場合は、1つの要素が完全一致する必要があります。 `sub`をルールの`subject_prefix`と比較します（大文字と小文字を区別します。末尾の`*`はプレフィックス一致で、それ以外は完全一致です）。ルールの`claims`マップ内のすべてのキーを、同じ名前のトップレベルのクレームと比較します。 `exp`は未来の時刻、`nbf`/`iat`は過去の時刻である必要があり、30秒のスキュー範囲内で判定されます。ワークロードホストの時計がずれている場合、本来は有効なトークンが拒否されます。 `discovery`モードの場合は、ポート443のパブリックHTTPS経由で`/.well-known/openid-configuration`を取得し、`jwks_uri`が解決されることを確認します。`explicit_url`の場合は、JWKS URLを直接取得します。`inline`の場合は、キーを登録してからイシュアーの署名キーがローテーションされていないことを確認します。 イシュアーが署名キーをローテーションし、すぐにそのキーで署名を開始した場合、AnthropicのJWKSキャッシュが更新されるまでの最大1分間、交換が失敗することがあります。[キーのローテーションとキャッシュ](https://platform.claude.com/docs/ja/manage-claude/wif-reference#key-rotation-and-caching)を参照してください。 ## JWKSソースモード フェデレーションイシュアーを登録する際、`jwks`フィールドは、そのイシュアーからのJWT署名を検証するために使用する公開鍵をAnthropicがどのように取得するかを制御します。これは`type`をキーとする判別共用体です。 | `jwks.type` | `jwks`の形式 | 動作 | 使用する場面 | | ------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `discovery`（デフォルト） | `{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base`は任意です。ディスカバリーURLが`issuer_url`と異なる場合に設定します） | Anthropicは`/.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からTLSを提供するイシュアー向けに、任意の`ca_cert_pem`文字列も受け付けます。 ### キーのローテーションとキャッシュ `discovery`および`explicit_url`モードでは、Anthropicは取得したJWKSをキャッシュします。IDプロバイダーが新しい署名キーを公開し、すぐにそのキーでトークンの署名を開始した場合、キャッシュが更新されるまでの最大1分間、それらのトークンを提示する交換が署名エラーで失敗することがあります。 この期間を回避するには、IDプロバイダーが新しい署名キーでトークンの署名を開始する少なくとも15分前にそのキーをJWKSで公開し、置き換えられたキーは、そのキーで署名されたトークンの有効期限が切れるまでJWKSに残しておいてください。マネージドIDプロバイダーは通常、この手順を自動的に守っています。独自のイシュアー（セルフマネージドKubernetesクラスター、SPIRE OIDCディスカバリープロバイダー、またはローテーション周期が設定されたOktaカスタム認可サーバー）を運用している場合は、ローテーションポリシーが新しいキーを初回使用前に公開するようになっていることを確認してください。 `inline`モードでは、キーの自動更新は行われません。IDプロバイダーが署名キーをローテーションした場合は、新しいJWKSでイシュアーの設定を更新する必要があります。更新しないと、すべてのトークン交換が署名検証に失敗します。