ワークロード ID フェデレーション

ワークロード ID フェデレーションを使用すると、個人アクセストークンや その他の長期間有効な OpenAI 認証情報を保存せずに、信頼できる自動処理から Codex を使用できます。ワークロードは、 すでに運用しているプロバイダーから短期間有効な ID トークンを提示します。 OpenAI はそのトークンを検証し、管理対象の ChatGPT ワークスペース内にあるユーザーまたは サービスアカウント用の短期間有効なアクセストークンを返します。

クラウドプラットフォーム、Kubernetes、CI システム、および OIDC トークンや SPIFFE JWT-SVID を発行できるその他の環境で、無人実行される Codex プロセスにはワークロード ID を使用してください。 共有信頼モデルと、別個の OpenAI API フローについては、 ワークロード ID の概要を参照してください。

始める前に

次のものが必要です。

• OpenAI Admin Portal でワークロード ID を管理する権限。
• 管理対象の ChatGPT ワークスペース。
• そのワークスペースのアクティブなメンバーである ChatGPT ユーザーまたはサービスアカウント、 あるいはセットアップ中に作成する権限。
• 発行者、オーディエンス、識別用クレームが 判明している OIDC トークンまたは SPIFFE JWT-SVID。
• そのトークンを絶対パスにある保護されたファイル内で最新の状態に 維持できるランタイム。
• Codex 0.148.0 以降。
• ChatGPT 認証と、フェデレーションルールで選択されたワークスペースを許可する、 有効な Codex 認証ポリシー。ログイン 方法またはワークスペースを適用するを参照してください。

OpenAI は、トークン交換時にプリンシパルやワークスペースのメンバーシップを 作成しません。ワークロードが接続する前に、管理者がプリンシパルを選択または 作成します。人間のユーザーを作成するとワークスペースのシートを消費し、その ワークスペースのメンバーシップルールが適用されます。

ネイティブ Windows では、elevated Windows sandbox を使用してください。他の Windows sandbox モードでは、 モデルが制御するコマンドから ID トークンファイルを保護できません。

ID トークンを取得する

ワークロードのランタイムが上流の ID トークンを取得し、更新します。Codex が 代わりにクラウドメタデータサービスや ID プロバイダーのクライアントライブラリを 呼び出すことはありません。

プロバイダー向けのガイドに従ってトークンの発行を構成し、 サンプルトークンを確認してください。

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

サンプルトークンをローカルでデコードし、その iss、aud、sub、および信頼する予定のその他の クレームを記録してください。デコードでは署名は検証されません。本番環境の トークンを Web サイトに貼り付けたり、ログへ書き込んだりしないでください。

ワークロードを接続する

Codex を起動する前に、管理者がプロバイダーとフェデレーションルールを 作成します。

1. OpenAI Admin Portal で Workload identity を開き、 Connect workload を選択します。
2. Codex 用に構成済みのプロバイダーを再利用するか、新規作成します。プロバイダーのプリセットには、 GitHub Actions、Microsoft Entra ID、Google Cloud、 AWS、Kubernetes、SPIFFE、カスタム OIDC プロバイダー向けの一般的な設定が入力されます。
3. Codex と、ワークロードが使用できる管理対象ワークスペースを選択します。
4. ワークロードを識別するための条件を必要最小限に絞って追加します。サブジェクト、 完全一致クレーム、CEL 条件、またはその組み合わせを照合します。許可するオーディエンスを追加し、 ルールが受け入れるトークンを制限します。構成されたすべてのマッチャーを満たす必要があります。
5. ルールを既存の ChatGPT ユーザーまたはサービスアカウント 1 つにマッピングするか、 セットアップ中に作成します。
6. プロバイダー、条件、ワークスペース、プリンシパル、スコープ、アクセス トークンの有効期間を確認します。Connect workload、続いて Download config を選択します。

ダウンロードしたファイルには、シークレットではないフェデレーションルール ID と、 Codex が ID トークンを読み取るパスが含まれます。認証情報は含まれません。

セットアップを自動化するには、ワークロード ID Admin API を使用してください。マッチャーの 動作と例については、フェデレーションルールの リファレンスを参照してください。

Codex プロセスを構成する

Codex を起動するプロセスには、次の 2 つのワークロード ID 変数が必要です。

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID はシークレットではありません。トークンファイルはシークレットです。ワークロードアカウントが所有し、 モード 0700 が設定された /var/run/secrets/openai.com など、専用ディレクトリ内の絶対 パスを使用してください。そこへ書き込めるのは、信頼できるホストプロセスだけにします。 ディレクトリは、リポジトリや Codex ツールからアクセス可能なその他のパスの外部に配置してください。 認証情報をログ、シェル履歴、ビルド成果物に含めないでください。

監査アトリビューションを追加する

複数のランタイムインスタンスでフェデレーションルールを共有する場合は、トークン発行の監査イベントで 各インスタンスを識別できます。省略可能な OPENAI_WORKLOAD_IDENTITY_CONTEXT 変数に、文字列としてエンコードされた JSON オブジェクトを 設定します。

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

オブジェクトには instance_id が必須です。display_name と最大 8 個のラベルも含められます。エンコードされたオブジェクトの上限は 1,024 バイトです。instance_id と display_name の上限は 128 文字です。ラベルキーの上限は 64 文字、ラベル値の上限は 256 文字です。

識別子は ASCII 文字または数字で始める必要があります。それ以降の値には、 文字、数字、.、_、:、/、@、- を使用できます。ラベルキーでは、文字、 数字、.、_、- を使用できます。

OpenAI はこのコンテキストを、検証済みのワークロード ID ではなく、クライアントから報告された 監査アトリビューションとして扱います。認証、認可、ルールの 照合、スコープ、レート制限、失効、機能ゲート、メトリクスには影響しません。ここには、 認証情報、シークレット、個人データ、プロンプト、モデル出力、その他の Customer Content を含めないでください。

有効なコンテキストの場合、OpenAI はテナント、 プロバイダー、フェデレーションルール、instance_id の範囲内で安定したアトリビューション ID を生成します。アトリビューションのため、アクセストークンには ID が含まれますが、コンテキストは含まれません。成功したトークン発行の監査イベントには、 ID と正規化されたコンテキストが含まれます。制限を超えるか このスキーマに違反するコンテキストでは、交換が invalid_grant で失敗します。

Codex はプロセス起動時にコンテキストを読み取り、それ、ルール ID、トークンファイルのパスを、モデルが制御するシェル、フック、MCP サーバーへ渡しません。 コンテキストを変更した後は Codex を再起動してください。

トークンファイルを保護してローテーションする

管理対象の Linux、macOS、WSL デプロイでは、トークンディレクトリ全体を、管理対象要件の permissions.filesystem.deny_read に追加します。

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

これにより、モデルが制御するコマンドから有効なトークンや一時的な 置換ファイルを読み取れなくなる一方、Codex ホストプロセスは引き続きトークンを交換に 使用できます。投影トークンボリュームでは、トークンのマウント全体と、その外部にある バックエンドまたは解決後の対象パスをすべて拒否してください。ファイルモードと環境変数の 除去だけでは、同じユーザーとして動作する別のプロセスから認証情報を保護できません。 ネイティブ Windows では、前述の elevated sandbox を使用してください。

ファイルを投影しないトークンソースでは、信頼できるホストプロセスに、 各置換ファイルをその保護されたディレクトリ内へ書き込ませてから、所定の場所に名前を変更させます。 アトミックな名前変更により、Codex が不完全なトークンを読み取ることを防げます。たとえば、 次のホスト所有の更新スクリプトをプロバイダーのトークンコマンドに合わせて調整してください。スクリプトを実行する前に、 ディレクトリをプロビジョニングします。

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

更新プロセスは、Codex が制御できるシェルやツールの外部で実行してください。 更新中とクリーンアップ中も読み取り拒否を維持してください。強制停止によって 一時ファイルが残った場合でも、そのファイルは拒否対象の ディレクトリ内にとどめる必要があります。ワークロード ID の設定を config.toml に含めないでください。

接続を確認する

ダウンロードした環境を読み込み、選択された認証方法を確認します。

. ./workload-identity-idpm_example.env
codex login status

PowerShell の場合：

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

チェックに成功すると Logged in using workload identity と表示されます。これは、 Codex が構成されたフェデレーションルールを介してトークンを交換したことを示します。このコマンドは、 解決されたワークスペース、プリンシパル、ルールを表示しません。ワークロードを起動する前に、 Admin Portal でこれらの値を確認してください。Codex が別の 認証方法を報告する場合、必須の 2 つの WIF 変数がプロセスに渡されていません。

プロバイダーが Prevent assertion replay を使用し、アサーションに jti クレームがある場合、このチェックでその jti が消費されます。別の Codex プロセスを起動する前に、 新しい jti を持つ、新たに発行されたアサーションを書き込んでください。

同じ環境から小さなリクエストを実行します。

codex exec "Reply with only: workload identity is working"

Codex は上流のトークンを交換し、OpenAI アクセストークンをメモリ内に保持します。 どちらの認証情報も auth.json、システムのキーリング、 config.toml には書き込みません。

トークンを最新の状態に保つ

上流トークンの有効期限が切れる前に、ID トークンファイルを更新してください。Codex は、 別の OpenAI アクセストークンが必要になったときにファイルを再読み込みします。OpenAI トークンの有効期限は、 上流トークンの有効期限またはフェデレーションルールの有効期間のうち早い方となり、 1 時間を超えることはありません。

管理者がリプレイ保護を有効にしている場合、上流の各 JWT には一意の jti が必要です。長時間実行プロセスでの更新を含め、交換のたびに新しい jti を持つ、 新たに発行されたアサーションを書き込んでください。jti のないアサーションには リプレイ保護が適用されません。

Codex は各ホストプロセス内で 1 つのメモリ内交換セッションを共有します。そのプロセス内の同時 リクエストは、有効な OpenAI アクセストークンを再利用し、有効期限が切れたときの更新を 1 回に まとめます。別々のプロセスは個別に交換を行うため、 プロバイダーがそれぞれに使用を許可するアサーションが必要です。

認証情報の優先順位

必須の 2 つのワークロード ID 変数は、他のすべての 認証情報ソースより優先されます。

1. OPENAI_FEDERATION_RULE_ID または OPENAI_IDENTITY_TOKEN_FILE のいずれかが存在する場合、Codex はワークロード ID を選択します。
2. 必須変数が 1 つしか存在しない場合、Codex はエラーを返します。API key、 アクセストークン、保存済みログインにはフォールバックしません。
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT だけではワークロード ID は選択されません。
4. 必須の WIF 変数がどちらも存在しない場合、Codex はそのサーフェスの通常の 認証情報ルールを適用します。API key 認証が許可されるサーフェスでは、 CODEX_API_KEY が codex exec、 codex review、TypeScript SDK、codex exec-server --remote で優先されます。その他の サーフェスでは、CODEX_ACCESS_TOKEN または保存済みログインを使用できます。

SDK の apiKey オプションは CODEX_API_KEY になりますが、必須の WIF 変数のいずれかが存在する場合は、 引き続き WIF が優先されます。WIF を使用するときは、ワークロードが未使用の 長期間有効な認証情報を保持しないよう、このオプションを省略してください。

既存のワークロードをダウンタイムなしで移行するには、現在の 認証情報を引き続き利用できる間に WIF を構成します。必須の WIF 変数を両方設定して新しいプロセスを起動すると、古い認証情報が残っていても WIF が優先されます。 ワークロードが WIF で正常に動作した後、ランタイムと シークレットストアから古い認証情報を削除し、失効させます。失効前であれば、 必須の WIF 変数を両方削除して新しいプロセスを起動することでロールバックできます。

サポートされる Codex サーフェス

Codex プロセスを所有するマシンでワークロード ID を構成してください。

リモートの app-server および exec-server クライアントは、そのプロトコル経由で上流の ID トークンを送信することはありません。

アクセスを変更または削除する

ルールのサブジェクト、オーディエンス、クレーム、CEL 条件、スコープ、トークン 有効期間への変更は、新しい交換に適用されます。変更前に発行されたトークンは、 有効期間が終了するまで有効な場合があります。

アクセスを直ちに停止するには、プロバイダーまたはルールを無効にします。無効化すると新しい 交換がブロックされ、そのリソースを介して発行済みの OpenAI アクセストークンも失効します。 アーカイブもアクセスに同じ効果を与え、元に戻すことはできません。プロバイダーの 信頼設定を変更した場合も、新しい信頼設定が有効になる前に発行済みトークンが失効します。

変更を監査する

プロバイダーとフェデレーションルールの作成、更新、アーカイブにより、監査 イベントが生成されます。Compliance API と監査イベントの ガイダンスを使用して、ワークスペースが サポートするイベントをエクスポートしてください。それらを ID プロバイダーの発行ログと関連付け、どちらのシステムにも 上流のアサーションや OpenAI アクセストークンを記録しないでください。

プロセスが OPENAI_WORKLOAD_IDENTITY_CONTEXT を提供する場合、成功した トークン発行の監査イベントには、前述の安定したアトリビューション ID と 正規化されたコンテキストも含まれます。

トラブルシューティング

プロバイダーの検証、制限、CEL の詳細については、フェデレーションルールの リファレンスを参照してください。