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は次の順序で認証情報を解決します。最初に認証情報を得られたソースが採用されます。

ant CLIでは、Claude Models on Google Cloud (Anthropic managed)の設定の優先順位は、フェデレーション環境変数より低く、アクティブなプロファイルより高くなります。設定とは、プロジェクト、ワークスペースID、およびロケーションです。これらは--google-cloud-*フラグまたはANTHROPIC_GOOGLE_CLOUD_*変数で設定します。CLIは、これらの設定のいずれか1つでも設定されている場合にこれらの設定を使用します。これらの設定を使用すると、CLIはGoogle Application Default Credentialsから資格情報を取得します。

プロファイルが読み込まれると、環境変数はプロファイルで省略されているフィールドを補完しますが、プロファイルで明示的に設定されたフィールドを上書きすることはありません。たとえば、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は交換の失敗をWorkloadIdentityErrorとして報告し、HTTPステータスとレスポンスボディのエラー詳細を提供します。リクエストIDは、Python、TypeScript、Rubyではエラー上に、Javaでは例外のレスポンスヘッダーに含まれます。Goでは、エラーの型が内部パッケージにあるため、エラーメッセージ内にのみ含まれます。C#とPHPのエラーにはリクエスト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をキャッシュします。IDプロバイダーが新しい署名キーを公開し、すぐにそのキーでトークンの署名を開始した場合、キャッシュが更新されるまでの最大1分間、それらのトークンを提示する交換が署名エラーで失敗することがあります。

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