AI API ゲートウェイのキーレス アップストリーム認証: Workload Identity フェデレーション パターン
更新停止を引き起こしたり、ID マッピングを弱めたり、共有資格情報にサイレントにフォールバックしたりすることなく、有効期間の長いプロバイダー キーをワークロード ID と有効期間の短いトークンに置き換えます。
プロバイダーがワークロード自体を認証できる場合、本番ゲートウェイのワーカーは、有効期間の長いアップストリーム API キーを保持すべきではありません。より安全なパターンは、既存のクラウド、Kubernetes、CI、または SPIFFE ID を有効期間の短いプロバイダー認証情報と交換し、その認証情報を正しくキャッシュし、有効な最小限の承認境界に制限することです。
難しい部分はトークン交換ではありません。広範な特権を持つ共有キーへの隠れたフォールバックを作成することなく、不均一なプロバイダーのサポート、同時更新、ID マッピング、コントロール プレーンの例外、停止、移行を処理します。
グローバルなキーレス設定ではなく、認証機能から始めます
事実: 認証サポートはプロバイダーと操作によって異なります。 OpenAI と Anthropic は、API 個のワークロードの Workload Identity フェデレーションをサポートします。 Azure OpenAI は、Microsoft Entra ID とマネージド ID をサポートしています。 Google クラウドは、外部ワークロードの接続されたサービス アカウント、アプリケーションのデフォルト認証情報、および Workload Identity Federation をサポートします。ただし、ランタイム推論と管理 API は、必ずしも同じ認証情報の種類を受け入れるとは限りません。
たとえば、OpenAI Workload Identity トークンは現在、管理者 API エンドポイントを呼び出すことができません。したがって、ゲートウェイは認証を auth_mode: federated.
推奨事項: プロバイダー アカウント、エンドポイント ファミリ、環境、操作クラスをキーとした機能マトリックスを構築します:
| プロバイダ アカウント | 操作 | 優先認証 | 許可される例外 |
|---|---|---|---|
| プロバイダ A 運用 | ランタイム推論 | OIDC 交換 | 通常運用中はなし |
| プロバイダ A 運用 | 組織管理 | 管理資格情報 | 分離されたコントロール プレーンワーカー |
| Azure デプロイ | ランタイム推論 | マネージド ID | 承認された緊急手順 |
| Vertex AI プロジェクト | ランタイム推論 | アプリケーションのデフォルト認証情報 | 外部ワークロード連携 |
このマトリックスをバージョン管理された構成として保存します。設定された ID が必要な認証機能を満たせない場合、ルート アドミッションは操作を拒否する必要があります。これは、個々のワーカーの文書化されていない環境変数ではなく、開発者チームの AI API コントロール プレーン に属します。
ルーティング アダプターとプロバイダー アダプターの間に認証情報ブローカーを配置します
プロバイダー アダプターは、メタデータ資格情報の取得、アサーションの構築、トークンの更新の管理を個別に行うべきではありません。 1 つの狭いインターフェイスを持つ認証情報ブローカーを導入します:
Credential acquire(CredentialRequest request)
CredentialRequest {
provider_account_id
workload_identity_id
operation_class
target_service_account
audience
scopes
}
Credential {
value
expires_at
authorization_context
provenance
}
認証情報の値は機密であるため、メモリまたは承認された一時キャッシュに保存する必要があります。認可コンテキストは、トークンによって表されるプロバイダー プロジェクト、サービス アカウント、スコープ、ロール、またはデプロイメント制限を記録します。来歴は、oidc_exchange、managed_identity、adc、break_glass など、取得方法を識別します。
この契約は、認可チェックとテレメトリに必要な詳細を保持しながら、プロバイダー中立のルーティングを維持します。また、チーム用 マルチモデル API ゲートウェイ がすべてのベアラー トークンを交換可能として扱うことも防止します。
プロバイダー固有の取得アダプターを使用する
各取得アダプターは、そのプロバイダーが必要とする手順のみを実行する必要があります:
- Kubernetes の投影されたサービス アカウント トークン、クラウド メタデータ サービス、SPIFFE ワークロード API などのローカル ID ソースから外部アサーションを取得します。
- プロバイダーまたは構成されたフェデレーション ルールが期待する正確な対象ユーザーを要求します。
- プロバイダーがトークン交換を必要とする場合は、アサーションを交換します。
- 結果を返します資格情報と権限の有効期限。
- 失敗をローカル ID、交換、認可、構成、またはプロバイダーの可用性エラーとして分類します。
Vertex AI の OpenAI 互換エンドポイントは、分離の有用な例です。アプリケーションは、アプリケーションのデフォルト認証情報を通じて Google アクセス トークンを取得し、そのトークンを OpenAI クライアントの認証情報として提供できます。プロトコル アダプターは OpenAI 互換性を維持しますが、資格情報の取得は Google 固有のままです。
トークン キャッシュを認証対応にする
事実: フェデレーション認証情報の有効期間は短くなります。 OpenAI Workload Identity アクセス トークンの持続時間は 1 時間以内であり、外部サブジェクト トークンまたは検証済み証明書よりも長く存続することはできず、更新トークンなしで発行されます。ワークロードは、有効期限が切れる前に交換を繰り返す必要があります。
キャッシュ キーには、結果として得られる権限を変更できるすべてのディメンションが含まれている必要があります:
cache_key = hash(
provider_account_id,
workload_identity_id,
target_service_account,
audience,
normalized_scopes,
operation_class
)
ターゲット アカウント、対象者、またはスコープを省略すると、ワーカーが間違った承認コンテキストで有効なトークンを再利用する可能性があります。これはキャッシュミスよりも危険です。
安全マージンとランダム化されたジッターを使用して、有効期限が切れる前にリフレッシュします。実際的なポリシーの 1 つは次のとおりです:
refresh_at = expires_at
- max(configured_margin, token_lifetime * 0.10)
- random_jitter
正確なマージンには、クロック スキュー、交換レイテンシー、再試行時間、予想される最長リクエストを考慮する必要があります。 expires_at.
単一フライトの更新でエクスチェンジ ストームを防止
多くのリクエストで有効期限が近い同じトークンが発生した場合、交換は 1 回の実行のみで行う必要があります。他の呼び出し元は、許可されたウィンドウ内にある限り既存の資格情報を使用し続けるか、共有更新結果を少し待つ必要があります。
キャッシュキーごとのシングルフライトロックを使用します。マルチプロセスまたはマルチノードのデプロイメントでは、各ワーカーが独自のキャッシュを維持できるかどうか、または更新調整を分散する必要があるかどうかを決定します。ローカル キャッシュはシンプルですが、交換量が増加します。分散キャッシュは交換を減らしますが、機密トークンの境界を拡大し、暗号化されたトランスポート、厳格なアクセス制御、および慎重な削除を必要とします。
推奨事項: プロバイダの制限やフリート サイズによって共有トークン サービスの必要性が示されない限り、インプロセス キャッシュを優先します。まず各プロセス内で更新を調整してから、交換量を測定します。
正確なワークロード要求に ID をバインドする
フェデレーションは、保存されたキーから ID クレームに信頼を移行します。したがって、寛容なマッピングは、共有認証情報の漏洩と同じくらい危険である可能性があります。
発行者と対象ユーザーを検証し、マッピングを不変または厳密に制御されたクレームにバインドします。 Kubernetes の場合は、クラスター内のワークロードを信頼するのではなく、名前空間とサービス アカウントを含めます。 CI の場合は、リポジトリ、ワークフロー、環境、保護されたブランチまたはデプロイメント コンテキストを制限します。クラウド ID の場合は、テナント全体または組織全体ではなく、特定のワークロード プリンシパルをマッピングします。
本番環境、ステージング、バックグラウンド ジョブ、管理自動化用に個別のアップストリーム サービス アカウントまたはマネージド ID を作成します。各 ID をモデル、プロジェクト、ワークスペース、デプロイメント、および API 必要な操作に制限します。
事実: OpenAI は、API 権限を持つ Workload Identity マッピングを制限できます。 Anthropic は、交換された資格情報をサービス アカウントに関連付け、フェデレーションの安全性はアップストリームの ID 構成と同じであることを警告します。マネージド ID とクラウド IAM も同様に、スコープが正しく設定されたロールの割り当てに依存します。
実行時認証情報を管理認証情報から分離する
一部のコントロール プレーン タスクが組織管理者トークンを必要とするという理由だけで、推論ワーカーは組織管理者トークンを継承してはなりません。システムを 2 つのセキュリティ境界に分割します:
- ランタイム プレーン: モデル リクエストを処理し、推論範囲のフェデレーションまたは管理された資格情報のみを受信します。
- コントロール プレーン: 個別に保存された資格情報と強力な承認制御を使用して、分離されたジョブを通じてプロジェクト、ワークスペース、請求、またはサービス アカウントの管理を実行します。
管理資格情報には、ランタイム環境変数、ポッド仕様、デバッグ バンドル、またはトークン キャッシュへのパスがあってはなりません。構成変更に使用されるのと同じ追加専用監査システムでそれらの使用を記録します。
即席のリカバリを行わずにフェイルクローズ
推奨事項: 失敗したフェデレーション交換を共有静的キーに自動的に置き換えないでください。自動フォールバックは、取り消されたマッピングをバイパスしたり、間違った対象ユーザーを隠したり、ID 管理者が意図的に削除したアクセスを復元したりすることができます。
分類されたアップストリーム認証エラーを返し、影響を受けるプロバイダー アカウントへのディスパッチを停止し、テナントとワークロードで代替プロバイダーが許可されている場合にのみ、通常のルーティング ポリシーで別のプロバイダーを選択できるようにします。モデルのフォールバックと資格情報のフォールバックは異なる決定です。
ID プロバイダーの重大な停止に対しては、非常用キーが正当化される可能性があります。通常の操作では無効にするかアクセスできないようにしてください。アクティベーションには認証された承認が必要であり、有効期限が固定されており、影響を受けるプロバイダー アカウントと操作を制限し、それを使用して行われるすべてのリクエストに対して警告を発する必要があります。その来歴はリクエスト テレメトリに表示される必要があります。
一度に 1 つのルーティング プールを移行します
- ランタイムと管理者の認証情報をインベントリします。それぞれを読み取ることができるプロセスを特定します。
- 専用のワークロード ID と範囲が狭いプロバイダー サービス アカウントを作成します。
- 正確な発行者、対象者、サブジェクト、権限のマッピングを構成します。
- トークンを取得し、影響の少ない許可されたエンドポイントを呼び出すプリフライト チェックを追加します。
- フェデレーションのみを使用して小規模なルーティング プールをカナリアします。テスト中は自動キー フォールバックを有効にしたままにしないでください。
- 認証の失敗、交換レイテンシ、トークンの経過時間、プロバイダ認証の結果を既存のパスと比較します。
- トラフィックを徐々に増やし、少なくとも 1 回の完全なトークン更新サイクルを観察します。
- 古いキーをランタイム アクセスから削除し、定義された観察期間の後に取り消します。
プロバイダー アカウントと環境ごとにこのプロセスを繰り返します。グローバル カットオーバーにより、ID マッピング エラーとプロバイダー固有のトークンの動作を区別することが困難になります。
故障モードを計測してテストする
トークン交換の遅延、更新の試行、更新の失敗、資格情報の経過時間、発行者、マップされたプリンシパル、プロバイダー アカウント、操作クラス、および認証エラー カテゴリを記録します。アクセス トークン、外部アサーション、クライアント シークレット、または完全な認証ヘッダーは決して記録しないでください。
フェデレーションが唯一の実稼働パスになる前に、次のテストを行ってください:
- ワーカー、ID プロバイダ、プロバイダ トークン サービス間のクロック スキュー。
- メタデータ サーバーまたはワークロード ID エンドポイントが利用できない。
- 期限切れのアサーションと間違った対象者。
- ロールの削除とフェデレーション ルールの無効化。
- トークン交換のスロットルと一時的なプロバイダー エラー。
- トラフィックのピーク時の同時更新。
- 古いトークンが有効なまま署名キーのローテーションを実行。
OIDC 発行者のローテーションでは、検証者のキャッシュと発行されたトークンに十分な重複を持たせて、古い署名鍵と新しい署名鍵を公開します。 OpenAI は、トークンが不明なキー ID を参照する場合に JWKS を更新する、検出およびリモート JWKS データの 600 秒のキャッシュを文書化します。すべての検証者が同じように動作すると想定しないでください。ライブカナリアを使用してローテーションをテストします。
制限された移行としてキーレス ランタイム認証を採用する
目標は、ゲートウェイに秘密が含まれていないと主張することではありません。これは、有効期間の長いプロバイダー キーを大容量のランタイム ワーカーから削除し、避けられない管理資格情報をより小さなコントロール プレーン境界に制限することです。
機能マトリックスから開始し、1 つのインターフェイスを通じて認証情報を仲介し、認可コンテキストごとにキャッシュし、正確な ID マッピングを使用し、交換エラーでフェールクローズします。更新、取り消し、停止、および署名キーのローテーションのテストが成功したことを確認した後でのみ、移行を完了してください。これにより、可用性と認証動作が想定されるものではなく理解されるキーレス ランタイム パスが生成されます。