Claude Media
Workload Identity Federation(WIF)とは — APIキー不要のClaude認証
AnthropicAgent SDK解説

Workload Identity Federation(WIF)とは — APIキー不要のClaude認証

ClaudeのWIFはIdPが発行する短命JWTをAnthropicのトークンと交換し、静的なAPIキーを持たずに認証する仕組みです。仕組みと移行手順をまとめます。

読了目安 約10分

Workload Identity Federationとは何か

Workload Identity Federation(WIF)は、ワークロードが sk-ant-... で始まる静的なAPIキーを持たずにClaude APIへ認証する仕組みです。AWS IAM・Google Cloud・GitHub Actions・Kubernetes・Microsoft Entra ID・Okta・SPIFFEなど、すでに運用しているIdP(アイデンティティプロバイダー)が発行した短命のOIDCトークンを、Anthropicが管理する短命のアクセストークンと交換します。発行・保管・ローテーション・漏えい対応が要る静的シークレットが、原理的に存在しなくなります。

WIFはセキュリティ対策の全部ではありません。連合された認証の強度は、JWTに署名する上流のIdPの強度を超えません。ワークロードIDバインディングや条件付きアクセス、監査ログといったIdP側の統制と組み合わせて初めて多層防御になります。

WIFを構成する3つのリソース

Claude Consoleで連合を組む前に、3種類のリソースを用意します。この3つがそろって初めてJWTの交換が成立します。

サービスアカウント(svac_...)は、組織内に置く人間ではないアイデンティティです。メールもパスワードもConsoleログインも持ちません。トークン交換のたびに指定するワークスペースがサービスアカウントのメンバーシップと一致しているかをAnthropicが確認し、発行したトークンはそのワークスペースのレート制限と利用量帰属に従います。ワークスペースAPIキーが「資格情報そのもの」であるのに対し、サービスアカウントは「資格情報を持つ主体」という違いがあり、どのワークロードがどのサービスアカウントとして動いたかを監査しやすくなります。

連合発行者(fdis_...)は、OIDCのIdPを組織に登録するリソースです。登録時に指定するのは、JWTのissクレームと完全一致する発行者URLと、公開鍵の取得方式(JWKS)です。JWKSは/.well-known/openid-configurationから自動取得するdiscovery(既定)、URLを直接指定するexplicit_url、エアギャップ環境向けに鍵セットをそのまま貼るinlineの3方式から選びます。発行者URLとJWKSのURLはHTTPS・443番ポート・パブリックDNSホスト名が必須で、IPリテラルは受け付けません(この制約はAnthropicが実際にフェッチするURLだけに適用され、explicit_urlとinlineではissuer_urlは文字列比較のため内部ホスト名も使えます)。本番用EKSクラスター・ステージング用クラスター・GitHub Actionsのように、環境ごとに発行者を分けて登録するのが基本です。

連合ルール(fdrl_...)は、発行者とサービスアカウントを結ぶ橋渡しです。「発行者Xからの、クレームがYに見えるJWTなら、サービスアカウントZとしてスコープSのトークンを発行する」という条件式にあたります。マッチ条件はsubject_prefix(末尾*で前方一致)・完全一致のaudience・完全一致マップのclaims・複雑な論理用のCEL condition式の組み合わせで、このうちsubject_prefix・claims・conditionのいずれか1つは必須です(audienceだけを単独指定してもこの必須条件は満たせません)。付与するOAuthスコープの既定はworkspace:developer(ワークスペースAPIキーと同等の権限)で、MCPトンネル作成のようにworkspace:manage_tunnelsへ固定されるフローもあります。1つの発行者に対して、チームや権限レベルごとに複数のルールを持たせられます。

Claude Consoleでの設定手順

Claude ConsoleのSettings → Workload identityにあるConnect workloadウィザードが、サービスアカウント・連合発行者・連合ルールの3つをまとめて作成します。IdPのタイル(GitHub Actions・AWS・Google Cloud・Microsoft Entra ID・Kubernetes)を選ぶと、その発行者URLのパターンとJWTが持つマッチ用フィールドが自動で入力されます。標準準拠の他のOIDCプロバイダー(SPIFFEやOktaなど)にはCustom OIDCを使います。

ウィザードはoauth_scope=workspace:developerとtoken_lifetime_seconds=600をあらかじめ入力していますが、ワークロードに応じて変更できます。Verify issuerを選ぶと、何も作成せずにJWKSを取得・解析できるかだけを事前確認できるため、URLの誤入力に早い段階で気づけます。最後にウィザードが3リソースを作成したあと、15分間トークン交換の成功を待ち受けます。この間にワークロードから交換を発生させて設定を確認します。時間切れになってもリソース自体は残るため、連合ルールの詳細ページから再テストできます。

トークン交換はどう動くか

WIFの認証は3ステップで完結します。

  1. IdPがワークロードにJWTを発行する。KubernetesのProjected Service Account Token、Google Cloudのメタデータサーバー、Azure IMDS、GitHub ActionsのOIDCエンドポイントなど、多くの環境ではこの発行が自動で起きます。JWTのissクレームが発行元を、subクレームなどが個々のワークロードを識別します。
  2. SDKがJWTをAnthropicのアクセストークンと交換する。SDKはRFC 7523のグラントを使い、へJWTをPOSTします。AnthropicはJWTを発行者のJWKSと連合ルールのマッチ条件に照らして検証し、ルールが指すサービスアカウントとして動く短命のトークンを返します。
  3. SDKがトークンを毎リクエストに乗せ、失効前に更新する。アプリケーションコードはapi_keyを指定せずにクライアントを構築し、あとは通常どおりAPIを呼ぶだけです。SDKが交換と更新のループを裏側で回します。
JWT=$(cat /var/run/secrets/anthropic.com/token)
 
RESPONSE=$(curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "$JWT",
  "federation_rule_id": "fdrl_...",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "service_account_id": "svac_...",
  "workspace_id": "wrkspc_..."
}
JSON
)
 
ACCESS_TOKEN=$(jq -r .access_token <<<"$RESPONSE")

実際のアプリケーションでは、SDKが提供するWorkloadIdentityCredentials(Python)やoidcFederationProvider(TypeScript)のようなヘルパーに任せるのが基本です。cURLを直接叩くのはデバッグ時に限られます。

APIキーからWIFへ移行する4ステップ

すでにAPIキーで動いているワークロードを、ダウンタイムなしでWIFへ切り替える手順は次の4段階です。

  1. WIFを並行して設定する。Claude ConsoleのSettings → Workload identityでConnect workloadを選び、IdPに応じたタイル(GitHub Actions・AWS・Google Cloud・Microsoft Entra ID・Kubernetes・Custom OIDC)からウィザードを進めます。既存のANTHROPIC_API_KEYはまだ残したままにします。
  2. どちらの資格情報が勝つかを確認する。ワークロード内でant auth statusを実行するか、SDKのデバッグログを見ます。ANTHROPIC_API_KEYは連合系の階層より優先順位が上なので、この時点ではまだAPIキーが選ばれます。
  3. ANTHROPIC_API_KEYをすべての箇所からunsetする。CIのシークレット・コンテナの環境変数・シェルのプロファイルから外します。再度ant auth statusを実行し、連合経路が選ばれたことを確認します。
  4. APIキーを削除する。ワークロードが連合トークンで動いていることを確認したら、Claude ConsoleのSettings → API keysからキー自体を削除します。

APIキーとWIFはどちらが勝つか

SDKは5段階の優先順位で認証情報を解決し、最初に見つかった情報源で確定します。上位が下位を黙って覆い隠す設計なので、移行の途中でどちらが勝つかを把握していないとハマります。

優先順位情報源
1情報源コンストラクタ引数(api_key=等)
2情報源ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN
3情報源ANTHROPIC_PROFILE(明示指定)
4情報源連合用の環境変数(4変数がすべて揃うと有効化)
5情報源アクティブなプロファイル

移行で最もハマりやすいのは、ANTHROPIC_API_KEY=""のように空文字列でエクスポートしたままにするケースです。空文字列でもスロットを占有するため、SDKは空キーのままAPIキー経路を選び、連合へフォールバックしません。unsetで完全に消す必要があります。優先順位の全表・プロファイルファイルのスキーマ・各階層の詳しい挙動はWIFリファレンスにまとめています。

WIFに向く運用、まだ早い運用

CI/CDのジョブやKubernetesのPodのように、実行のたびに使い捨てのアイデンティティを持てるワークロードにはWIFがよく合います。GitHub ActionsのOIDCトークンやKubernetesのProjected Tokenをそのまま使え、組織がAPIキー認証を無効化した環境でも運用を止めずに済みます。Managed Agentsのようにサービスアカウント単位で権限を切り分けたい構成とも相性がよく、監査ログでどのワークロードがどのサービスアカウントとして動いたかを追いやすくなります。クラウドごとの具体的な連合手順は、AWSとの連携とMicrosoft Entra ID(Azure)との連携にまとめています。

一方、IdPを持たない個人開発や、そもそもCI/CDを組んでいない小規模な検証環境では、APIキー1本で足りる場面のほうが多いはずです。連合発行者とルールの設計・JWKSの到達性確認といった初期コストは、ワークロードの数が増えて初めて回収できます。

まとめ

WIFはIdPが発行した短命JWTをAnthropicの短命トークンと交換することで、静的なAPIキーを排除する仕組みです。サービスアカウント・連合発行者・連合ルールの3リソースを組み、既存のAPIキーと並行稼働させながら段階的に切り替えられます。落とし穴は優先順位の上位にAPIキーが残っている限り移行が完了しないことと、空文字列の環境変数がスロットを占有し続けることの2点です。クラウドごとの具体的な設定は、次に読む記事で手を動かせます。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →