SPIFFEでWIFを使用する

SPIFFEは、ワークロードにアイデンティティを発行するためのCNCF標準です。SPIREはそのオープンソースのリファレンス実装であり、いくつかの商用製品もSPIFFE準拠のアイデンティティを発行しています。Anthropicは、OIDC互換のJWT-SVIDを発行するあらゆるSPIFFE実装とフェデレーションします。実装の最新リストについては、SPIFFEプロジェクトサイトのCommercial software that implements SPIFFEを参照してください。

フェデレーションは、公開HTTPS URLにあるOIDCディスカバリードキュメントを通じて（discoveryモード、URL制約の対象）、またはJWKSを直接登録すること（inlineモード）のいずれかで機能します。

JWT-SVID仕様ではsubをワークロードのSPIFFE IDとして定義しており、SPIFFE Workload APIは取得時に呼び出し元がaudを指定することを要求しているため、これらのクレームは実装間で共通です。Anthropicはさらにissとiatを要求しますが、どちらもJWT-SVID仕様では必須とされていないため、両方を設定するように実装を構成してください（SPIREでは、issはjwt_issuerサーバー設定であり、iatは自動的に設定されます）。これらが整っていれば、このガイドのAnthropicを設定する、トークンを取得して使用する、ルールのスコープを設定するのセクションは、あらゆるSPIFFE実装に適用できます。

SPIFFEはすべてのワークロードにspiffe://<trust-domain>/<path>という形式の安定したアイデンティティURIを割り当て、SPIREはWorkload APIを通じてオンデマンドでそのアイデンティティをJWT-SVIDとして発行します。JWT-SVIDは通常の署名付きJWTであり、そのsubクレームはワークロードのSPIFFE IDで、audクレームは取得時にワークロードによって指定されます。

SPIREトラストドメインから標準OIDCへの橋渡しとなるのがSPIRE OIDC Discovery Providerです。これは、トラストドメインのJWT署名鍵のための/.well-known/openid-configurationとJWKSエンドポイントを公開するスタンドアロンのヘルパーです。ディスカバリープロバイダーが稼働していれば、JWT-SVIDは他のOIDCトークンと同様に検証されます。ディスカバリーURLをフェデレーション発行者として登録し、ワークロードのSPIFFE IDに一致するフェデレーションルールを作成し、ワークロードがそのJWT-SVIDをAnthropicのトークン交換エンドポイントに提示するようにします。

このページの例はSPIREを使用しており、SPIRE Agentが実行されるあらゆる場所（Kubernetesポッド、仮想マシン、ベアメタルホスト）に適用できます。



前提条件

• WIFの概念（サービスアカウント、フェデレーション発行者、フェデレーションルール）に精通していること。
• ワークロードアイデンティティが発行されているSPIFFEデプロイメント（このページの例ではSPIRE ServerとAgentを使用）と、Claude APIを呼び出す必要があるワークロードの登録エントリ。
• トラストドメイン用のOIDCディスカバリーエンドポイント（SPIREではOIDC Discovery Provider）が公開されたHTTPSエンドポイントで到達可能な状態で稼働していること、またはinline登録用にエクスポートされたJWKS。
• JWT-SVIDのissクレームが、フェデレーション発行者のissuer_urlとして登録する値に設定されるようにSPIFFE発行者が構成されていること。discoveryモードの場合、これはディスカバリーエンドポイントの公開URL（SPIREではjwt_issuerサーバー設定）です。
• ワークロードがJWT-SVIDを利用できること。WIFはJWT-SVIDのみを受け入れ、X.509-SVIDは受け入れません。
• AnthropicオーガニゼーションのClaude Consoleでサービスアカウント、フェデレーション発行者、フェデレーションルールを作成する権限。

JWT-SVIDを取得する際にリクエストするオーディエンス値は常にhttps://api.anthropic.comです。この値をspiffe-helperのjwt_audience、Workload APIのFetchJWTSVID呼び出し、およびフェデレーションルールのaudienceマッチャーで使用してください。



SPIREを設定する

このセクションの手順はSPIRE固有のものです。別のSPIFFE発行者を使用する場合は、その発行者のドキュメントに従ってOIDCディスカバリーエンドポイントとJWT-SVIDの取得を構成し、Anthropicを設定するから続けてください。

すでにOIDC Discovery Providerと共にSPIREを実行している場合、Anthropicとのフェデレーションには、SPIRE側で3つのことが必要です。ディスカバリーURLと一致するjwt_issuer、Claude APIを呼び出すワークロードの登録エントリ、そしてそのワークロードがAnthropicオーディエンスでJWT-SVIDを取得する方法です。以下のサブセクションでそれぞれを順に説明します。設定スニペットは、Anthropicフェデレーションに関連する設定のみを示しており、完全なSPIREデプロイメント設定ではありません。



JWT発行者を確認する

Anthropicは、JWT-SVIDのissクレームを登録済みのフェデレーション発行者と照合し、その発行者のディスカバリードキュメントからJWKSを取得することで、JWT-SVIDを検証します。2つのSPIRE設定が同じURLで一致している必要があります。SPIRE Serverのjwt_issuer（発行されるすべてのJWT-SVIDのissクレームになります）と、OIDC Discovery Providerのdomainsリスト（ディスカバリードキュメントとJWKSが提供されるホストを決定します）です。この共有URLがAnthropicに登録するものです。

トラストドメインと発行者URLは独立しています。トラストドメイン（spiffe://prod.example.com）はsubクレームのスコープを定めます。発行者URL（https://oidc-discovery.prod.example.com）はAnthropicが署名鍵を取得する場所です。これらは同じホスト名を共有する必要はありません。

SPIRE Serverの設定でjwt_issuerが設定されており、ディスカバリープロバイダーの公開URLを指していることを確認してください。以下の例では、デフォルトのJWT-SVIDの有効期間も示しています。SPIREの組み込みデフォルトは5分で、これは継続的なローテーションが必要になるほど短いものです（spiffe-helperを実行するを参照）。Anthropicのトークン交換エンドポイントは、有効期間がフェデレーション発行者の設定された最大値（デフォルトでは1時間）を超えるアイデンティティトークンを拒否します（検証ルールを参照）。このチェックはSPIREだけでなくすべてのSPIFFE実装に適用されるため、default_jwt_svid_ttl（またはエントリごとのオーバーライド）をその最大値以下に保ってください。

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

OIDC Discovery Providerの設定では、同じホスト名がdomainsの下に記載されている必要があり、プロバイダーはSPIRE ServerのAPIソケットに到達できる必要があります。プロバイダーはディスカバリードキュメントとJWKSをHTTPS経由で提供します。組み込みのACMEサポートでTLSを終端するか、TLSを終端するロードバランサーを前段に配置してください。

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}



ワークロードを登録する

Claude APIを呼び出す各ワークロードには、そのランタイムセレクターをSPIFFE IDにマッピングするSPIRE登録エントリが必要です。ワークロードがすでに登録されている場合は、そのSPIFFE IDをメモしてください。これはフェデレーションルールのsubject_prefixで使用します。登録されていない場合は登録してください。Kubernetesポッドの場合、セレクターは通常、名前空間とKubernetesサービスアカウントです。

# NODE_UIDをノードのUIDに置き換えてください:
#   kubectl get node <node-name> -o jsonpath='{.metadata.uid}'
spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Kubernetes外のワークロードは、unix:uid:1000などのホストレベルのセレクターを使用します（unix:pathも利用可能ですが、エージェントのunixワークロードアテスター設定でdiscover_workload_path = trueが必要です）。spire-controller-managerを実行しているクラスターでは、spire-server entry createを直接呼び出す代わりに、ClusterSPIFFEIDカスタムリソースでエントリを宣言できます。



spiffe-helperを実行する

spiffe-helperは、SPIRE Agentソケットに接続し、指定されたオーディエンスのJWT-SVIDを取得してファイルに書き込み、有効期限前に再取得するサイドカーユーティリティです。ヘルパーはデフォルトでデーモンモードで実行されます。以下の例ではdaemon_mode = trueを明示的に設定しています。

agent_address = "/run/spire/sockets/agent.sock"
# The JWT-SVID file is written under cert_dir
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

Kubernetesでは、spiffe-helperをサイドカーコンテナとして実行し、アプリケーションコンテナとメモリバックのemptyDirボリューム（medium: Memory）を共有することで、ベアラーSVIDがノードのディスクに書き込まれないようにします。ホストからSPIRE Agentソケットをサイドカーにマウントし、共有ボリュームを両方のコンテナの/var/run/secrets/anthropic.comにマウントし、アプリケーションコンテナにANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/tokenを設定します。VMやベアメタルでは、spiffe-helperをワークロードと並行してシステムサービスとして実行し、両方を共有ディレクトリに向けます。



Anthropicを設定する

Claude Consoleで、Settings → Workload identityを開き、Connect workloadをクリックして、Custom OIDCを選択します。ウィザードが発行者の登録、サービスアカウントの作成、フェデレーションルールの作成を順に案内します。

ウィザードがこれらのリソースを作成します。ウィザードに入力する場合でも、Admin API に送信する場合でも、以下の値を使用してください。

フェデレーション発行者: OIDC Discovery Providerの公開URLをdiscoveryモードで登録します。AnthropicはこのURLから/.well-known/openid-configurationを取得し、返されたjwks_uriをたどってトラストドメインの署名鍵を取得します。

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

ディスカバリープロバイダーが公開インターネットから到達できない場合は、自分でJWKSを取得し（curl https://oidc-discovery.prod.example.com/keys）、返されたkeys配列の内容を使用して"jwks": {"type": "inline", "keys": [...]}で発行者を登録してください。inlineモードでは、issuer_urlはJWT-SVIDのissクレームとの比較にのみ使用されます。Anthropicがそこに到達しようとすることはありません。

公開ディスカバリーエンドポイントを公開せずにJWKSの更新を自動化するには、SPIRE ServerのBundlePublisherプラグイン（aws_s3、gcp_cloudstorage、またはk8s_configmap）をformat = "jwks"で設定して、ローテーションのたびにJWT署名鍵を外部ストレージにプッシュし、その後Admin APIを通じて発行者のインライン鍵を更新します。

フェデレーションルール: JWT-SVIDのsub（SPIFFE ID）と、spiffe-helperがリクエストするように設定したaudを照合します。SPIFFE IDはURI文字列であり、subject_prefixはそれらを不透明なテキストとして照合するため、完全一致の値でも末尾*のプレフィックス一致でも機能します。より複雑なパターンには、CELのconditionを使用してください。

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

token_lifetime_secondsは、交換が返すAnthropicアクセストークンの有効期間であり、JWT-SVIDの有効期間ではありません。SDKはアクセストークンを自動的に更新します。

ワークロードが許す限り具体的に指定してください。subject_prefixをspiffe://prod.example.com/ns/inference/*に緩めるのは、そのパスの下に登録されたすべてのワークロードが同じAnthropicサービスアカウントにマッピングされるべき場合のみにしてください。ルールのfdrl_... IDをワークロードのANTHROPIC_FEDERATION_RULE_ID環境変数に追加します。



トークンを取得して使用する

Anthropic SDKは、spiffe-helperが維持するファイルからJWT-SVIDを読み取るか、トークンプロバイダーのcallableを通じてSPIFFE Workload APIを直接呼び出すことができます。ファイルパスは最もシンプルな統合方法であり、すべてのSDK言語で機能します。callableの方法はサイドカーを不要にしますが、アプリケーションの言語でSPIFFE Workload APIクライアントが必要です。

import anthropic

# spiffe-helper が次のファイルに書き込む JWT-SVID を読み取ります:
# ANTHROPIC_IDENTITY_TOKEN_FILE。さらに ANTHROPIC_FEDERATION_RULE_ID、
# ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_SERVICE_ACCOUNT_ID、ANTHROPIC_WORKSPACE_ID も読み取ります。
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))



セットアップを確認する

SDKを組み込む前に、SPIRE Agentから直接JWT-SVIDを取得し、クレームがフェデレーションルールの期待するものと一致することを確認してください。別のSPIFFE実装を使用している場合は、そのCLIまたはWorkload APIクライアントでJWT-SVIDを取得し、同じ方法でペイロードをデコードしてください。

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

-output jsonフラグはSVIDレスポンスとバンドルレスポンスを2要素のJSON配列として返すため、jq -r '.[0].svids[0].svid'で生のトークンを抽出できます。-outputがない古いSPIREバージョンでは、コマンドは代わりにラベル付きのブロックを出力します。その場合は、デフォルトの出力をawk '/^[[:space:]]*eyJ/{print $1; exit}'にパイプしてトークン行を抽出してください。issが登録したOIDC Discovery ProviderのURLであること、subがワークロードのSPIFFE IDであること、audにhttps://api.anthropic.comが含まれていることを確認してください。その後、トークンを取得して使用するのcURLの例を実行します。交換が成功すると、sk-ant-oat01-で始まるaccess_tokenが返されます。400 invalid_grantの場合は、失敗した交換のトラブルシューティングを参照してください。SPIRE側で最も一般的な原因は、SPIRE Serverのjwt_issuerとフェデレーション発行者として登録されたURLの不一致です。



ルールのスコープを設定する

SPIFFE IDのパス規約はオペレーターが定義するものであるため、フェデレーションルールのsubject_prefixマッチャーは、登録エントリが使用するパススキームを反映する必要があります。一般的なスキームには、spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>（spire-controller-managerのClusterSPIFFEIDリソースが出力するデフォルト）や、VMおよびベアメタルワークロード用のspiffe://<trust-domain>/host/<hostname>/<service>があります。

ルールのmatchブロックを、ユースケースに合う最も狭いスコープに固定してください。

• 1つのワークロードに固定する: subject_prefixを末尾に*のない完全なSPIFFE IDに設定します。
• 常にオーディエンスを設定する: ルールでaudienceを必須にし、spiffe-helper（またはWorkload API呼び出し）を同じ値で設定して、他のリライングパーティ向けに発行されたSVIDが拒否されるようにします。
• パスセグメントでスコープを設定する: spiffe://prod.example.com/ns/inference/*を使用して名前空間の下に登録されたすべてのワークロードに付与し、1つのルールを広げるのではなく、名前空間ごとに個別のルールとAnthropicサービスアカウントを作成します。
• トラストドメインごとに1つの発行者: 各SPIREトラストドメインには独自の署名鍵とOIDC Discovery Providerがあります。それぞれを個別のフェデレーション発行者として登録し、ルールが一致するSPIFFE IDを所有する発行者にルールをバインドしてください。



次のステップ