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を検証する際に、これらの制約を適用します。

パラメータの詳細とレスポンススキーマについては、Service accounts APIリファレンス、Federation issuers APIリファレンス、およびFederation rules 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は交換の失敗を型付きのFederationExchangeError（または各言語の同等物）でラップし、HTTPステータス、レスポンスボディ、およびrequest_idを公開します。

アサーションの拒否はすべて、どのチェックが失敗したかに関係なく、固定メッセージAuthentication failedを持つ同一の不透明な401 authentication_errorを返します。区別可能なエラーを返すと、呼び出し元がルール設定を探ることができてしまうためです。拒否理由は認証履歴の該当試行のエントリに記録されます。たとえば、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が配列の場合、いずれかの要素が正確に一致する必要があります。

4. 4

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

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

5. 5

   exp、nbf、iatを確認する

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

6. 6

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

   discoveryモードの場合は、<jwks.discovery_base or issuer_url>/.well-known/openid-configurationをポート443のパブリックHTTPS経由で取得し、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をキャッシュします。IDプロバイダーが新しい署名キーを公開してすぐにそのキーでトークンの署名を開始した場合、それらのトークンを提示する交換は、キャッシュが更新されるまで最大1分間、署名エラーで失敗する可能性があります。

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