SPIFFEでWIFを使用する

SPIFFEは、ワークロードにアイデンティティを発行するためのCNCF標準です。SPIREはそのオープンソースのリファレンス実装であり、いくつかの商用製品もSPIFFE準拠のアイデンティティを発行しています。Anthropicは、OIDC互換のJWT-SVIDを発行する任意の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を実装する商用ソフトウェアを参照してください。

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がエクスポートされていること。
• SPIFFE発行者が、JWT-SVIDのissクレームをフェデレーション発行者のissuer_urlとして登録する値に設定するように構成されていること。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サービスアカウントです。

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"
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でフェデレーション発行者を登録し、Anthropicサービスアカウントを作成し、フェデレーションルールを作成します。以下のSPIFFE固有の値を使用してください。

フェデレーション発行者： 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署名鍵を外部ストレージにプッシュし、それを発行者のインライン鍵に同期します。

フェデレーションルール： 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
}

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

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

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

セットアップを検証する

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を所有する発行者にバインドします。

次のステップ

• Workload Identity Federation：概念、トークン交換フロー、SDK構成オプション。
• WIFリファレンス：環境変数、JWKSソースモード、ルールマッチモード。
• KubernetesでWIFを使用する：SPIREの代わりにネイティブな投影サービスアカウントトークンを使用するクラスター向け。