管理認証

WIFリファレンス

Workload Identity Federationの環境変数、検証ルール、プロファイル設定、およびエラーリファレンス。

このページでは、Workload Identity Federationの設定項目、検証制約、およびエラーマッピングをまとめています。セットアップ手順については、プロバイダーガイドを参照してください。

トークン交換リクエスト

POST /v1/oauth/tokenは、RFC 7523のjwt-bearerグラントを使用したJSONボディを受け付けます。SDKは環境変数からこのリクエストを自動的に構築します。各プロバイダーガイドの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`。ルールが複数のワークスペースで有効になっている場合は必須です。省略した場合、サーバーはルールの唯一の有効なワークスペースを選択します。

トークン交換レスポンス

POST /v1/oauth/tokenは、標準のOAuth 2.0トークンレスポンス（RFC 6749 §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の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`。フェデレーションルールが複数のワークスペースで有効になっている場合は必須、ルールが単一のワークスペースにバインドされている場合は任意です。発行されるトークンは交換時にこのワークスペースにスコープされるため、ワークスペースを切り替えるには新しい交換が必要です。	`wrkspc_...`
`ANTHROPIC_PROFILE`	いいえ	読み込む設定プロファイルの名前。この表のフェデレーション環境変数よりも優先されます。	`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キーパスを選択します。使用しない認証情報変数は空にするのではなく、unsetしてください。

認証情報の優先順位

SDKは次の順序で認証情報を解決します。認証情報を提供する最初のソースが採用されます。

順序	ソース	備考
1	コンストラクタ引数（`api_key=`、`auth_token=`、`credentials=`）	常に他のすべてを上書きします。
2	`ANTHROPIC_API_KEY`または`ANTHROPIC_AUTH_TOKEN`	フェデレーションを完全に隠します。APIキーから移行する際はこれらをunsetしてください。
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は次の順序で設定ディレクトリを特定します。

$ANTHROPIC_CONFIG_DIR
LinuxおよびmacOSでは~/.config/anthropic
Windowsでは%APPDATA%\Anthropic

アクティブプロファイル

アクティブプロファイル名は次の順序で解決されます。

$ANTHROPIC_PROFILE
<config_dir>/active_configの内容（ant profile activate <name>によって書き込まれる1行のファイル）
リテラル名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`で書き込まれます。

設定ファイルと認証情報ファイルの両方に、major.minor形式（現在は"1.0"）のトップレベル文字列versionフィールドが含まれます。SDKはこのフィールドを自動的に書き込むため、将来のリリースで古い形式を検出して移行できます。設定を手動で作成する際にこれを省略すると、SDKはファイルを現在のバージョンとして扱います。

フェデレーションプロファイルの例

configs/production.json

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

authentication.identity_tokenが省略されている場合、SDKは環境のANTHROPIC_IDENTITY_TOKEN_FILEまたはANTHROPIC_IDENTITY_TOKENにフォールバックします。

OAuthスコープ

フェデレーションルールに設定するoauth_scopeは、発行されたアクセストークンが呼び出せるClaude APIエンドポイントを決定します。

スコープ	アクセス権限
`workspace:developer`	ルールのワークスペース内のすべての非管理系Claude APIエンドポイント：Messages（ストリーミングおよびトークンカウントを含む）、Models、Managed Agentsとそのセッション、Files、およびSkills。これは、同じワークスペースに対して発行されたAPIキーが持つアクセス権と一致します。
`org:manage_tunnels`	MCPトンネルAPI：トンネルの一覧表示と取得、CA証明書の登録とアーカイブ、トンネルトークンの表示とローテーション、トンネルのアーカイブ。Consoleのトンネル作成モーダルからルールを作成すると、このスコープがロックされます。

トークンのスコープ外のエンドポイントへのリクエストはHTTP 403を返します。より細かいスコープ（リソースごと、または読み取りと書き込みの区別）は現在利用できません。

検証ルール

Anthropicは、イシュアーとルールを作成または更新するとき、および交換時に受信JWTを検証するときに、これらの制約を適用します。

リソースフィールド

フィールド	制約
イシュアー、ルール、およびサービスアカウントの`name`	`^[a-z0-9-]+$`に一致し、長さは1〜255文字である必要があります。
`workspace_id`	任意。このルールで発行されるトークンに適用されるクォータ、請求、およびレート制限のワークスペース（`wrkspc_...`）。同じ組織内のワークスペースである必要があり、対象のサービスアカウントはそのワークスペースのメンバーである必要があります。1つのワークスペースのみに設定されているルールでは省略できます。
`token_lifetime_seconds`	`60`から`86400`（1分から24時間）の整数。デフォルトは`3600`。この範囲外の値はリクエスト時に拒否されます。トークンの有効期間とリフレッシュを参照してください。

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`が存在し、未来の時刻である必要があります。
最大有効期間	トークンの有効期間（`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<string, string>	各キーはトップレベルのクレーム名で、各値は必須の正確な文字列値です。ネストされたクレーム、数値、ブール値、またはリストやマップなどの複雑なクレームには、代わりにCEL式を使った`condition`を使用してください。
`condition`	string（CEL）	`true`に評価される必要があるCEL式。

CEL評価環境

condition式は単一の変数にアクセスできます。

変数	型	内容
`claims`	map	デコードされたJWTクレームセット全体。ネストされたオブジェクトはネストされたマップとしてアクセスできます。

例：

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

CEL条件はセキュリティ境界です。意図したよりも多くの入力に対してtrueと評価される式は、意図したよりも広いアクセスを許可します。制約を表現できる場合は、静的マッチャーを優先してください。

エラー

トークン交換エラー

POST /v1/oauth/tokenは、標準のAPIエラー形式でエラーを返します。SDKは交換の失敗を、HTTPステータス、レスポンスボディ、およびrequest_idを公開する型付きのFederationExchangeError（または言語ごとの同等のもの）でラップします。

ステータス	エラー	原因	解決策
400	`invalid_request`	`federation_rule_id`の形式が不正、または必須のリクエストフィールドが欠落しています。	`fdrl_` IDと、リクエストボディにすべての必須フィールドが含まれていることを確認してください。
400	`invalid_request`	`workspace_id_required`：フェデレーションルールが複数のワークスペースで有効になっており、リクエストで`workspace_id`が省略されています。	`ANTHROPIC_WORKSPACE_ID`（または生のリクエストの場合はボディフィールド`workspace_id`）を、トークンのスコープとしたい`wrkspc_...` IDに設定してください。トークン交換リクエストを参照してください。
400	`invalid_grant`	JWTの`iss`クレームが登録された`issuer_url`と正確に一致しません。	末尾のスラッシュやスキームを含め、バイト単位で比較してください：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKSのフェッチに失敗した、JWKSが古い、またはJWTがJWKSにないキーで署名されています。	`inline`モードの場合、ローテーションされたキーでイシュアーを更新してください。`discovery`および`explicit_url`の場合、JWKSエンドポイントがポート443で到達可能であることを確認してください。イシュアーが最近署名キーをローテーションした場合は、キーローテーションとキャッシングを参照してください。
400	`invalid_grant`	JWTの`exp`クレームが過去の時刻です（30秒のスキューウィンドウを超えています）。	IDプロバイダーが新しいトークンをプロジェクトしており、SDKがトークンファイルを再読み込みしていることを確認してください。
400	`invalid_grant`	JWTは検証されましたが、そのクレームがルールの`match`ブロックを満たしていません。	JWTをデコードし、各クレームをルールと比較してください。`subject_prefix`は大文字と小文字を区別します。`audience`は要素の完全一致が必要です。
400	`invalid_grant`	`federation_rule_id`が存在しない、アーカイブされている、またはJWTがそれに対して認可されていません（列挙を防ぐために統合されています）。	Claude ConsoleでルールIDを確認し、ルールがアーカイブされていないことを確認してください。

すべてのinvalid_grantの失敗はHTTP 400を返します。具体的な原因はサーバー側でのみログに記録され、レスポンスには公開されません。

一般的な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`が設定されており、優先順位で勝っています。	キーまたはトークン変数をunsetしてください。
最初のリクエストで`FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE`のパスが存在しません。SDKは交換時に遅延してファイルを開きます。	プロジェクテッドトークンボリュームがマウントされており、パスが一致していることを確認してください。
トークン交換は成功するが、Claude APIリクエストが403を返す	発行されたトークンのスコープがそのエンドポイントへのアクセスを許可していません。	ルールの`oauth_scope`をOAuthスコープと照合してください。
空の認証情報で認証が失敗する	認証情報の環境変数がエクスポートされていますが、空文字列に設定されています。空の値でも優先順位スロットを占有します。	`VAR=""`ではなく`unset VAR`で変数をunsetしてください。

失敗した交換のトラブルシューティング

400 invalid_grantレスポンスは意図的に不透明です。具体的な原因はサーバー側でのみログに記録されます。

まずClaude Consoleの認証履歴ページから始めてください。最近の交換試行では、評価されたイシュアーとルール、検査されたJWTクレーム、およびどの検証ステップが失敗したかが表示されるため、通常は以下のチェックを省略できます。

それでもJWT自体からデバッグする必要がある場合は、次のチェックを順番に実行してください。

JWTをデコードする
送信したアサーションをデコードして、各クレームをイシュアーおよびルールの設定と比較できるようにします。
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
issがイシュアーと一致することを確認する
デコードされたissクレームは、スキーム、ポート、および末尾のスラッシュを含め、登録されたissuer_urlとバイト単位で一致する必要があります。1文字でも不一致があると検証に失敗します。
audがルールと一致することを確認する
デコードされたaudクレームには、ルールのaudience値が完全一致として含まれている必要があります。audが配列の場合、1つの要素が正確に一致する必要があります。
subと各claimsエントリを確認する
subをルールのsubject_prefixと比較します（大文字と小文字を区別。末尾の*はプレフィックスマッチ、それ以外は完全一致）。ルールのclaimsマップ内のすべてのキーを、同じ名前のトップレベルクレームと比較します。
exp、nbf、iatを確認する
expは未来の時刻であり、nbf/iatは過去の時刻である必要があります（30秒のスキューウィンドウ内）。ワークロードホストのクロックがずれている場合、それ以外は有効なトークンでも拒否されます。
JWKSの到達可能性を確認する
discoveryモードの場合、パブリックHTTPSのポート443経由で<jwks.discovery_baseまたはissuer_url>/.well-known/openid-configurationをフェッチし、jwks_uriが解決されることを確認します。explicit_urlの場合、JWKS URLを直接フェッチします。inlineの場合、キーを登録してからイシュアーの署名キーがローテーションされていないことを確認します。
イシュアーが署名キーをローテーションし、すぐにそれで署名を開始した場合、AnthropicのJWKSキャッシュがリフレッシュされるまで最大1分間、交換が失敗する可能性があります。キーローテーションとキャッシングを参照してください。

JWKSソースモード

フェデレーションイシュアーを登録する際、jwksフィールドは、AnthropicがそのイシュアーからのJWT署名を検証するために使用する公開鍵を取得する方法を制御します。これはtypeをキーとする判別共用体です。

`jwks.type`	`jwks`の形式	動作	使用する場合
`discovery`（デフォルト）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base`は任意。ディスカバリーURLが`issuer_url`と異なる場合に設定します）	Anthropicは`<discovery_baseまたは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からTLSを提供するイシュアー向けに、オプションのca_cert_pem文字列も受け付けます。

キーローテーションとキャッシング

discoveryおよびexplicit_urlモードでは、AnthropicはフェッチしたJWKSをキャッシュします。IDプロバイダーが新しい署名キーを公開し、すぐにそれでトークンの署名を開始した場合、それらのトークンを提示する交換は、キャッシュがリフレッシュされるまで最大1分間、署名エラーで失敗する可能性があります。

このウィンドウを回避するには、IDプロバイダーが新しい署名キーでトークンの署名を開始する少なくとも15分前にJWKSに新しい署名キーを公開し、置き換えられたキーで署名されたトークンが期限切れになるまで、そのキーをJWKSに保持してください。マネージドIDプロバイダーは通常、この規律を自動的に守ります。独自のイシュアー（セルフマネージドKubernetesクラスター、SPIRE OIDCディスカバリープロバイダー、またはローテーション周期が設定されたOktaカスタム認可サーバー）を運用している場合は、ローテーションポリシーが初回使用前に新しいキーを公開していることを確認してください。

inlineモードでは、自動キーリフレッシュはありません。IDプロバイダーが署名キーをローテーションした場合、新しいJWKSでイシュアー設定を更新する必要があります。そうしないと、すべてのトークン交換が署名検証に失敗します。

Was this page helpful?

管理認証

WIFリファレンス

Workload Identity Federationの環境変数、検証ルール、プロファイル設定、およびエラーリファレンス。

トークン交換リクエスト

フィールド	必須	説明
`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`。ルールが複数のワークスペースで有効になっている場合は必須です。省略した場合、サーバーはルールの唯一の有効なワークスペースを選択します。

トークン交換レスポンス

POST /v1/oauth/tokenは、標準のOAuth 2.0トークンレスポンス（RFC 6749 §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の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`。フェデレーションルールが複数のワークスペースで有効になっている場合は必須、ルールが単一のワークスペースにバインドされている場合は任意です。発行されるトークンは交換時にこのワークスペースにスコープされるため、ワークスペースを切り替えるには新しい交換が必要です。	`wrkspc_...`
`ANTHROPIC_PROFILE`	いいえ	読み込む設定プロファイルの名前。この表のフェデレーション環境変数よりも優先されます。	`staging-profile`

認証情報の優先順位

SDKは次の順序で認証情報を解決します。認証情報を提供する最初のソースが採用されます。

順序	ソース	備考
1	コンストラクタ引数（`api_key=`、`auth_token=`、`credentials=`）	常に他のすべてを上書きします。
2	`ANTHROPIC_API_KEY`または`ANTHROPIC_AUTH_TOKEN`	フェデレーションを完全に隠します。APIキーから移行する際はこれらをunsetしてください。
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`という名前のプロファイルにフォールバックします。

プロファイル設定ファイル

設定ディレクトリ

SDKは次の順序で設定ディレクトリを特定します。

$ANTHROPIC_CONFIG_DIR
LinuxおよびmacOSでは~/.config/anthropic
Windowsでは%APPDATA%\Anthropic

アクティブプロファイル

アクティブプロファイル名は次の順序で解決されます。

$ANTHROPIC_PROFILE
<config_dir>/active_configの内容（ant profile activate <name>によって書き込まれる1行のファイル）
リテラル名default

ファイルレイアウト

パス	内容	機密性
`<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`で書き込まれます。

フェデレーションプロファイルの例

configs/production.json

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

authentication.identity_tokenが省略されている場合、SDKは環境のANTHROPIC_IDENTITY_TOKEN_FILEまたはANTHROPIC_IDENTITY_TOKENにフォールバックします。

OAuthスコープ

フェデレーションルールに設定するoauth_scopeは、発行されたアクセストークンが呼び出せるClaude APIエンドポイントを決定します。

スコープ	アクセス権限
`workspace:developer`	ルールのワークスペース内のすべての非管理系Claude APIエンドポイント：Messages（ストリーミングおよびトークンカウントを含む）、Models、Managed Agentsとそのセッション、Files、およびSkills。これは、同じワークスペースに対して発行されたAPIキーが持つアクセス権と一致します。
`org:manage_tunnels`	MCPトンネルAPI：トンネルの一覧表示と取得、CA証明書の登録とアーカイブ、トンネルトークンの表示とローテーション、トンネルのアーカイブ。Consoleのトンネル作成モーダルからルールを作成すると、このスコープがロックされます。

検証ルール

Anthropicは、イシュアーとルールを作成または更新するとき、および交換時に受信JWTを検証するときに、これらの制約を適用します。

リソースフィールド

フィールド	制約
イシュアー、ルール、およびサービスアカウントの`name`	`^[a-z0-9-]+$`に一致し、長さは1〜255文字である必要があります。
`workspace_id`	任意。このルールで発行されるトークンに適用されるクォータ、請求、およびレート制限のワークスペース（`wrkspc_...`）。同じ組織内のワークスペースである必要があり、対象のサービスアカウントはそのワークスペースのメンバーである必要があります。1つのワークスペースのみに設定されているルールでは省略できます。
`token_lifetime_seconds`	`60`から`86400`（1分から24時間）の整数。デフォルトは`3600`。この範囲外の値はリクエスト時に拒否されます。トークンの有効期間とリフレッシュを参照してください。

URLフィールド

issuer_url、jwks.discovery_base、およびjwks.urlフィールドは検証されます。

制約	詳細
スキーム	`https`である必要があります。
ポート	`443`（明示的またはデフォルト）である必要があります。
ホスト	OIDCプロバイダーのパブリックDNSホスト名である必要があります。パブリックIPアドレスに解決される必要があり、IPリテラルは受け付けられません。

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`が存在し、未来の時刻である必要があります。
最大有効期間	トークンの有効期間（`exp`から`iat`を引いた値）は、イシュアーに設定された最大値（デフォルトは1時間、Claude Consoleで各イシュアーごとに設定可能）を超えてはなりません。
クロックスキュー	`exp`、`nbf`、および`iat`には30秒の許容範囲が適用されます。

ルールマッチングのセマンティクス

マッチャー	型	セマンティクス
`subject_prefix`	string	JWTの`sub`クレームとの完全一致。末尾の``はプレフィックスマッチにします（`sub`の値は``の前の文字で始まる必要があります）。大文字と小文字を区別します。
`audience`	string	JWTの`aud`クレームにこの文字列が正確に含まれている必要があります。`aud`が配列の場合、いずれかの要素が正確に一致すればチェックを満たします。
`claims`	map<string, string>	各キーはトップレベルのクレーム名で、各値は必須の正確な文字列値です。ネストされたクレーム、数値、ブール値、またはリストやマップなどの複雑なクレームには、代わりにCEL式を使った`condition`を使用してください。
`condition`	string（CEL）	`true`に評価される必要があるCEL式。

CEL評価環境

condition式は単一の変数にアクセスできます。

変数	型	内容
`claims`	map	デコードされたJWTクレームセット全体。ネストされたオブジェクトはネストされたマップとしてアクセスできます。

例：

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

エラー

トークン交換エラー

ステータス	エラー	原因	解決策
400	`invalid_request`	`federation_rule_id`の形式が不正、または必須のリクエストフィールドが欠落しています。	`fdrl_` IDと、リクエストボディにすべての必須フィールドが含まれていることを確認してください。
400	`invalid_request`	`workspace_id_required`：フェデレーションルールが複数のワークスペースで有効になっており、リクエストで`workspace_id`が省略されています。	`ANTHROPIC_WORKSPACE_ID`（または生のリクエストの場合はボディフィールド`workspace_id`）を、トークンのスコープとしたい`wrkspc_...` IDに設定してください。トークン交換リクエストを参照してください。
400	`invalid_grant`	JWTの`iss`クレームが登録された`issuer_url`と正確に一致しません。	末尾のスラッシュやスキームを含め、バイト単位で比較してください：`jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`。
400	`invalid_grant`	JWKSのフェッチに失敗した、JWKSが古い、またはJWTがJWKSにないキーで署名されています。	`inline`モードの場合、ローテーションされたキーでイシュアーを更新してください。`discovery`および`explicit_url`の場合、JWKSエンドポイントがポート443で到達可能であることを確認してください。イシュアーが最近署名キーをローテーションした場合は、キーローテーションとキャッシングを参照してください。
400	`invalid_grant`	JWTの`exp`クレームが過去の時刻です（30秒のスキューウィンドウを超えています）。	IDプロバイダーが新しいトークンをプロジェクトしており、SDKがトークンファイルを再読み込みしていることを確認してください。
400	`invalid_grant`	JWTは検証されましたが、そのクレームがルールの`match`ブロックを満たしていません。	JWTをデコードし、各クレームをルールと比較してください。`subject_prefix`は大文字と小文字を区別します。`audience`は要素の完全一致が必要です。
400	`invalid_grant`	`federation_rule_id`が存在しない、アーカイブされている、またはJWTがそれに対して認可されていません（列挙を防ぐために統合されています）。	Claude ConsoleでルールIDを確認し、ルールがアーカイブされていないことを確認してください。

すべてのinvalid_grantの失敗はHTTP 400を返します。具体的な原因はサーバー側でのみログに記録され、レスポンスには公開されません。

一般的な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`が設定されており、優先順位で勝っています。	キーまたはトークン変数をunsetしてください。
最初のリクエストで`FileNotFoundError`	`ANTHROPIC_IDENTITY_TOKEN_FILE`のパスが存在しません。SDKは交換時に遅延してファイルを開きます。	プロジェクテッドトークンボリュームがマウントされており、パスが一致していることを確認してください。
トークン交換は成功するが、Claude APIリクエストが403を返す	発行されたトークンのスコープがそのエンドポイントへのアクセスを許可していません。	ルールの`oauth_scope`をOAuthスコープと照合してください。
空の認証情報で認証が失敗する	認証情報の環境変数がエクスポートされていますが、空文字列に設定されています。空の値でも優先順位スロットを占有します。	`VAR=""`ではなく`unset VAR`で変数をunsetしてください。

失敗した交換のトラブルシューティング

400 invalid_grantレスポンスは意図的に不透明です。具体的な原因はサーバー側でのみログに記録されます。

それでもJWT自体からデバッグする必要がある場合は、次のチェックを順番に実行してください。

JWTをデコードする
送信したアサーションをデコードして、各クレームをイシュアーおよびルールの設定と比較できるようにします。
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
issがイシュアーと一致することを確認する
デコードされたissクレームは、スキーム、ポート、および末尾のスラッシュを含め、登録されたissuer_urlとバイト単位で一致する必要があります。1文字でも不一致があると検証に失敗します。
audがルールと一致することを確認する
デコードされたaudクレームには、ルールのaudience値が完全一致として含まれている必要があります。audが配列の場合、1つの要素が正確に一致する必要があります。
subと各claimsエントリを確認する
subをルールのsubject_prefixと比較します（大文字と小文字を区別。末尾の*はプレフィックスマッチ、それ以外は完全一致）。ルールのclaimsマップ内のすべてのキーを、同じ名前のトップレベルクレームと比較します。
exp、nbf、iatを確認する
expは未来の時刻であり、nbf/iatは過去の時刻である必要があります（30秒のスキューウィンドウ内）。ワークロードホストのクロックがずれている場合、それ以外は有効なトークンでも拒否されます。
JWKSの到達可能性を確認する
discoveryモードの場合、パブリックHTTPSのポート443経由で<jwks.discovery_baseまたはissuer_url>/.well-known/openid-configurationをフェッチし、jwks_uriが解決されることを確認します。explicit_urlの場合、JWKS URLを直接フェッチします。inlineの場合、キーを登録してからイシュアーの署名キーがローテーションされていないことを確認します。
イシュアーが署名キーをローテーションし、すぐにそれで署名を開始した場合、AnthropicのJWKSキャッシュがリフレッシュされるまで最大1分間、交換が失敗する可能性があります。キーローテーションとキャッシングを参照してください。

JWKSソースモード

`jwks.type`	`jwks`の形式	動作	使用する場合
`discovery`（デフォルト）	`{ "type": "discovery", "discovery_base": "https://..." }`（`discovery_base`は任意。ディスカバリーURLが`issuer_url`と異なる場合に設定します）	Anthropicは`<discovery_baseまたは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クラスター、またはキーローテーションを明示的に制御したい場合。

キーローテーションとキャッシング

Was this page helpful?