Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
このページでは、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のいずれか | 「identity provider」（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~/.config/anthropic%APPDATA%\Anthropicアクティブプロファイル名は次の順序で解決されます。
$ANTHROPIC_PROFILE<config_dir>/active_configの内容（ant profile activate <name>によって書き込まれる1行のファイル）defaultClaude 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はファイルを現在のバージョンとして扱います。
{
"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_scopeは、発行されたアクセストークンが呼び出せるClaude APIエンドポイントを決定します。
| スコープ | アクセスを付与する対象 |
|---|---|
workspace:developer | ルールのワークスペース内のすべての非管理Claude APIエンドポイント：Messages（ストリーミングおよびトークンカウントを含む）、Models、Managed Agentsとそのセッション、Files、およびSkills。これは、同じワークスペースに対して発行されたAPIキーが持つアクセス権と一致します。 |
workspace:inference | ルールのワークスペース内の推論エンドポイント：Messages（ストリーミングおよびトークンカウントを含む）、Models、およびOpenAI互換チャットエンドポイント。Claudeを呼び出すだけで、Files、Skills、その他のリソースを管理する必要がないワークロードに使用します。 |
workspace:manage_tunnels | MCPトンネルAPI：トンネルの作成、一覧表示、取得、CA証明書の登録とアーカイブ、トンネルトークンの表示とローテーション、およびトンネルのアーカイブ。Consoleのトンネル作成モーダルからルールを作成すると、このスコープがロックされます。 |
org:admin | Admin APIへの完全なアクセス（組織メンバー、招待、ワークスペース、APIキー、その他）。OAuthのorg:adminトークンは、workspace:developerまたはworkspace:inferenceにスコープされたルールのみを作成または変更でき、他のスコープを持つルールを支えるissuerを更新することはできません。制約を参照してください。 |
トークンのスコープ外のエンドポイントへのリクエストは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呼び出し元の除外事項を除きます。制約を参照してください。 |
Anthropicは、issuerとルールを作成または更新するとき、および交換時に受信JWTを検証するときに、これらの制約を適用します。
完全なパラメータの詳細とレスポンススキーマについては、Service accounts APIリファレンス、Federation issuers APIリファレンス、およびFederation rules APIリファレンスを参照してください。
| フィールド | 制約 |
|---|---|
issuer、ルール、およびサービスアカウントの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です。この範囲外の値はリクエスト時に拒否されます。トークンの有効期間とリフレッシュを参照してください。 |
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クレームと文字列として比較され、フェッチされることはないため、内部ホスト名や非標準ポートを参照できます。
| 制約 | 詳細 |
|---|---|
| 最大サイズ | assertion JWTは最大16 KiBである必要があります。 |
| 署名アルゴリズム | 非対称アルゴリズム（RSAおよびECDSAファミリー：ES256、ES384、ES512、RS256、RS384、RS512、PS256、PS384、PS512）のみが受け付けられます。HMAC（HS256、HS384、HS512）およびnoneは拒否されます。 |
| キーID | JWTヘッダーには、issuerのJWKS内のキーと一致するkidが含まれている必要があります。kidのないトークンは拒否されます。 |
| 必須クレーム | subが存在する必要があります。iatが存在し、未来でない必要があります。expが存在し、未来である必要があります。 |
| 最大有効期間 | トークンの有効期間（expからiatを引いた値）は、issuerに設定された最大値（デフォルトで1時間、Claude Consoleで各issuerごとに設定可能）を超えてはなりません。 |
| クロックスキュー | exp、nbf、およびiatに30秒の許容範囲が適用されます。 |
フェデレーションルールのmatchブロックは、受信JWTが受け入れられるかどうかを決定します。設定されたすべてのフィールドはANDセマンティクスで評価されます。JWTは設定されたすべてのマッチャーを満たす必要があります。subject_prefix、claims、またはconditionの少なくとも1つを設定する必要があります。audienceのみを含む（またはマッチャーをまったく含まない）matchブロックは拒否されます。これは、issuerからのすべてのトークンを受け入れてしまうルールを防ぐためです。
| マッチャー | 型 | セマンティクス |
|---|---|---|
subject_prefix | string | JWTのsubクレームに対する完全一致。末尾の*はプレフィックス一致にします（sub値は*の前の文字で始まる必要があります）。大文字と小文字を区別します。 |
audience | string | JWTのaudクレームにこの正確な文字列が含まれている必要があります。audが配列の場合、いずれかの要素が完全一致すればチェックを満たします。 |
claims | map<string, string> | 各キーはトップレベルのクレーム名で、各値は必須の正確な文字列値です。ネストされたクレーム、数値、ブール値、またはリストやマップなどの複雑なクレームには、代わりにCEL式を使用したconditionを使用してください。 |
condition | string（CEL） | trueと評価される必要がある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モードの場合、ローテーションされたキーでissuerを更新してください。discoveryおよびexplicit_urlの場合、JWKSエンドポイントがポート443で到達可能であることを確認してください。issuerが最近署名キーをローテーションした場合は、キーローテーションとキャッシングを参照してください。 |
| 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が交換する代わりに「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の認証履歴ページから始めてください。最近の交換試行では、評価されたissuerとルール、検査されたJWTクレーム、およびどの検証ステップが失敗したかが表示されるため、通常は以下のチェックを省略できます。
それでもJWT自体からデバッグする必要がある場合は、次のチェックを順番に実行してください。
JWTをデコードする
送信したアサーションをデコードして、各クレームをissuerおよびルール設定と比較できるようにします。
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"issがissuerと一致することを確認する
デコードされたissクレームは、スキーム、ポート、および末尾のスラッシュを含め、登録されたissuer_urlとバイト単位で一致する必要があります。1文字でも不一致があると検証に失敗します。
audがルールと一致することを確認する
デコードされたaudクレームには、ルールのaudience値が完全一致として含まれている必要があります。audが配列の場合、1つの要素が完全一致する必要があります。
subと各claimsエントリを確認する
subをルールのsubject_prefixと比較します（大文字と小文字を区別します。末尾の*はプレフィックス一致、それ以外は完全一致です）。ルールのclaimsマップ内のすべてのキーを、同じ名前のトップレベルクレームと比較します。
exp、nbf、およびiatを確認する
expは未来であり、nbf/iatは過去である必要があります（30秒のスキューウィンドウ内）。ワークロードホストのクロックがずれている場合、それ以外は有効なトークンでも拒否されます。
JWKSの到達可能性を確認する
discoveryモードの場合、ポート443のパブリックHTTPS経由で<jwks.discovery_base or issuer_url>/.well-known/openid-configurationをフェッチし、jwks_uriが解決されることを確認します。explicit_urlの場合、JWKS URLを直接フェッチします。inlineの場合、キーを登録してからissuerの署名キーがローテーションされていないことを確認します。
issuerが署名キーをローテーションし、すぐにそれで署名を開始した場合、AnthropicのJWKSキャッシュがリフレッシュされるまで最大1分間、交換が失敗する可能性があります。キーローテーションとキャッシングを参照してください。
フェデレーションissuerを登録する際、jwksフィールドは、Anthropicがそのissuerからの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比較にのみ使用されます。 | エアギャップ環境、クラスター内部のissuer URLを持つセルフマネージドKubernetesクラスター、またはキーローテーションを明示的に制御したい場合。 |
判別共用体により、付随するフィールドは構造上相互に排他的になります。discoveryとexplicit_urlの両方は、プライベートCAからTLSを提供するissuer用に、オプションのca_cert_pem文字列も受け付けます。
discoveryおよびexplicit_urlモードでは、AnthropicはフェッチしたJWKSをキャッシュします。IDプロバイダーが新しい署名キーを公開し、すぐにそれでトークンの署名を開始した場合、それらのトークンを提示する交換は、キャッシュがリフレッシュされるまで最大1分間、署名エラーで失敗する可能性があります。
このウィンドウを回避するには、IDプロバイダーが新しい署名キーでトークンの署名を開始する少なくとも15分前にJWKSに新しい署名キーを公開し、置き換えられたキーで署名されたトークンが期限切れになるまでそのキーをJWKSに保持してください。マネージドIDプロバイダーは通常、この規律を自動的に守ります。独自のissuer（セルフマネージドKubernetesクラスター、SPIRE OIDCディスカバリープロバイダー、またはローテーション周期が設定されたOktaカスタム認可サーバー）を運用している場合は、ローテーションポリシーが初回使用前に新しいキーを公開することを確認してください。
inlineモードでは自動キーリフレッシュはありません。IDプロバイダーが署名キーをローテーションした場合、新しいJWKSでissuer設定を更新する必要があります。そうしないと、すべてのトークン交換が署名検証に失敗します。
Was this page helpful?