--- 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` | はい | アイデンティティプロバイダーが発行した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`のいずれか | アイデンティティプロバイダー（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` は併せて読み取られますが、有効化を制御するものではありません。 空文字列に設定された変数は、資格情報の優先順位チェーンにおいて依然としてそのスロットを占有します。`ANTHROPIC_API_KEY=""` がエクスポートされている場合、SDK はフェデレーションにフォールスルーするのではなく、空のキーで API キーパスを選択します。未使用の資格情報変数は空白にするのではなく、設定を解除してください。 ### 資格情報の優先順位 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` という名前のプロファイルにフォールバックします。 | プロファイルが読み込まれると、環境変数はプロファイルが省略したフィールドを埋めますが、プロファイルが明示的に設定したフィールドを上書きすることはありません。たとえば、`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 を検証するときに、これらの制約を適用します。 パラメータの詳細とレスポンススキーマの全体については、[サービスアカウントAPIリファレンス](https://platform.claude.com/docs/ja/api/organization/service_accounts)、[フェデレーション発行者APIリファレンス](https://platform.claude.com/docs/ja/api/organization/federation/issuers)、および[フェデレーションルール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`クレームのないアサーションはこのチェックの対象外です。[フェデレーション発行者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: `*config.FederationExchangeError`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`)でラップし、HTTPステータス、レスポンスボディ、および`request_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 秒のスキューウィンドウを超えて）です。 | アイデンティティプロバイダーが新しいトークンを投影しており、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` が表示されます。 | トークンのスコープを限定したい `wrkspc_...` ID に `ANTHROPIC_WORKSPACE_ID`（または生のリクエストの `workspace_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 をキャッシュします。アイデンティティプロバイダーが新しい署名キーを公開し、すぐにそれでトークンの署名を開始した場合、それらのトークンを提示する交換は、キャッシュが更新される間、最大 1 分間署名エラーで失敗する可能性があります。 このウィンドウを回避するには、アイデンティティプロバイダーがトークンの署名を開始する少なくとも 15 分前に JWKS に新しい署名キーを公開し、それが署名したトークンが期限切れになるまで、置き換えられたキーを JWKS に保持してください。マネージドアイデンティティプロバイダーは通常、この規律を自ら守ります。独自の発行者（自己管理型 Kubernetes クラスタ、SPIRE OIDC ディスカバリプロバイダー、または設定されたローテーション頻度を持つ Okta カスタム認可サーバー）を運用している場合は、ローテーションポリシーが最初の使用前に新しいキーを公開することを確認してください。 `inline` モードでは、自動的なキー更新はありません。アイデンティティプロバイダーが署名キーをローテーションするとき、新しい JWKS で発行者設定を更新する必要があります。そうしないと、すべてのトークン交換が署名検証に失敗します。