WIF リファレンス

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

トークン交換リクエスト

POST /v1/oauth/tokenは、RFC 7523のjwt-bearerグラントを使用するJSONボディを受け付けます。SDKは環境変数からこのリクエストを自動的に構築します。各プロバイダーガイドのcURLの例では、生のボディを示しています。

トークン交換レスポンス

POST /v1/oauth/token は、標準的な OAuth 2.0 トークンレスポンス（RFC 6749 §5.1）を返します。

環境変数

SDK は、コンストラクタ引数なしでフェデレーショントークン交換を実行するために、これらの変数を読み取ります。

直接的な環境変数フェデレーションパスは、ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID、および ANTHROPIC_IDENTITY_TOKEN_FILE または ANTHROPIC_IDENTITY_TOKEN のいずれかがすべて設定されている場合にのみ有効になります。ANTHROPIC_WORKSPACE_ID は併せて読み取られますが、有効化を制御するものではありません。

資格情報の優先順位

SDK はこの順序で資格情報を解決します。資格情報を生成する最初のソースが優先されます。

プロファイルが読み込まれると、環境変数はプロファイルが省略したフィールドを埋めますが、プロファイルが明示的に設定したフィールドを上書きすることはありません。たとえば、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> によって書き込まれる 1 行のファイル）
3. リテラル名 default

Claude Code と Claude Agent SDK はこの同じ解決順序を尊重するため、ここで設定されたフェデレーションプロファイルは、追加のセットアップなしでこれらのツールも認証します。

ファイルレイアウト

設定ファイルと資格情報ファイルの両方には、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 スコープ

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

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

権限の境界

フェデレーションルールの oauth_scope は上限です。発行されるトークンがそれを超えることはありません。対象サービスアカウントの organization_role（developer または admin）は、どのスコープが付与可能かを決定するため、org:admin を付与するルールは organization_role=admin のサービスアカウントを対象にする必要があります。実効権限は、ルールのスコープとサービスアカウントのロールの積集合です。

検証ルール

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

パラメータの詳細とレスポンススキーマの全体については、サービスアカウントAPIリファレンス、フェデレーション発行者APIリファレンス、およびフェデレーションルールAPIリファレンスを参照してください。

リソースフィールド

URL フィールド

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

URL 検証の失敗は、エラーメッセージのプレフィックスとしてフィールド名を付けて 400 invalid_request_error を返します（たとえば、issuer_url: url must use https scheme）。

JWT 検証

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

フェデレーションルールの match ブロックは、受信 JWT が受け付けられるかどうかを決定します。設定されたすべてのフィールドは AND セマンティクスで評価されます。JWT はすべての設定されたマッチャーを満たす必要があります。subject_prefix、claims、または condition のうち少なくとも 1 つを設定する必要があります。audience のみを含む（またはマッチャーをまったく含まない）match ブロックは拒否されます。これにより、発行者からのすべてのトークンを受け付けてしまうルールを防ぎます。

CEL 評価環境

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

例：

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

エラー

トークン交換エラー

POST /v1/oauth/tokenは、標準のAPIエラー形式でエラーを返します。SDKは交換の失敗を型付きのWorkloadIdentityErrorでラップし、HTTPステータス、レスポンスボディ、およびrequest_idを公開します。

アサーションが拒否された場合は、どのチェックで失敗したかにかかわらず、固定メッセージAuthentication failedを伴う同一の不透明な401 authentication_errorが返されます。区別可能なエラーを返すと、呼び出し元がルール設定を探ることができてしまうためです。拒否理由は、Claude Consoleの認証履歴にある試行のエントリに記録されます。たとえば、subクレームがルールのsubject_prefixを満たさない場合はmatch_subject_prefix、ルールが複数のワークスペースにまたがっているのにリクエストでワークスペースが指定されていない場合はworkspace_id_requiredとなります。ルールの組織が確認される前に拒否されたリクエスト（上記の400 invalid_request_error系）は履歴エントリを残しません。それらのレスポンスメッセージは問題を直接示します。一致する履歴エントリのない401は、通常、federation_rule_id自体が認識されなかったことを意味します。

一般的な SDK 側の失敗

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

401 authentication_error レスポンスは意図的に不透明であり、そのメッセージは常に Authentication failed です。拒否理由はレスポンスではなく認証履歴に記録されます。

一般的な不透明な失敗の 1 つは、リプレイされたアサーションです。jti クレームを持つアサーションは1 回のみ交換できるため、同じ JWT を再送信するワークロード（リトライループ、またはローテーションされていないトークンを再読み込みする更新）は、2 回目の交換で拒否されます。認証履歴ページには、これらの試行が理由 jti_reused とともに表示されます。修正方法は、交換ごとに新しいアサーションを発行することです。

JWT 自体からデバッグする必要がある場合は、これらのチェックを順番に進めてください。

1. 1

   JWT をデコードする

   送信したアサーションをデコードして、各クレームを発行者とルールの設定と比較できるようにします。

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   iss が発行者と一致することを確認する

   デコードされた iss クレームは、スキーム、ポート、および末尾のスラッシュを含め、登録された issuer_url とバイト単位で一致する必要があります。1 文字でも不一致があると検証に失敗します。

3. 3

   aud がルールと一致することを確認する

   デコードされた aud クレームには、ルールの audience 値が完全一致として含まれている必要があります。aud が配列の場合、1 つの要素が完全に一致する必要があります。

4. 4

   sub と各 claims エントリを確認する

   sub をルールの subject_prefix と比較します（大文字と小文字を区別します。末尾の * はプレフィックス一致、それ以外は完全一致です）。ルールの claims マップ内のすべてのキーを、同じ名前のトップレベルクレームと比較します。

5. 5

   exp、nbf、および iat を確認する

   exp は未来であり、nbf/iat は過去である必要があります（30 秒のスキューウィンドウ内）。ワークロードホストのクロックがずれている場合、それ以外は有効なトークンが拒否されます。

6. 6

   JWKS の到達可能性を確認する

   discovery モードの場合、ポート 443 のパブリック HTTPS 経由で <jwks.discovery_base or issuer_url>/.well-known/openid-configuration をフェッチし、jwks_uri が解決されることを確認します。explicit_url の場合は、JWKS URL を直接フェッチします。inline の場合は、キーを登録してから発行者の署名キーがローテーションされていないことを確認します。

   発行者が署名キーをローテーションし、すぐにそれで署名を開始した場合、Anthropic の JWKS キャッシュが更新される間、最大 1 分間交換が失敗する可能性があります。キーのローテーションとキャッシングを参照してください。

JWKS ソースモード

フェデレーション発行者を登録するとき、jwks フィールドは、その発行者からの JWT 署名を検証するために使用される公開鍵を Anthropic がどのように取得するかを制御します。これは type をキーとする判別共用体です。

判別共用体により、コンパニオンフィールドは構造上相互に排他的になります。discovery と explicit_url の両方は、プライベート CA から TLS を提供する発行者のために、任意の ca_cert_pem 文字列も受け付けます。

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

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

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