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

ワークロード ID フェデレーションでは、信頼されたワークロードが OpenAI API キーや ChatGPT の認証情報を保存する代わりに、すでに持っている ID を使用できます。ワークロードが ID プロバイダーから取得した短期間有効なトークンを提示すると、OpenAI がそれを短期間有効な OpenAI アクセストークンと交換します。

OpenAI API のワークロードでは、X.509 ワークロード ID フェデレーションを通じて、検証済みの証明書 ID を使った交換も行えます。

ワークロード ID フェデレーションは、OpenAI API または Codex で使用できます。

どちらも同じ信頼モデルを使用しますが、管理方法とランタイムの設定が異なります。まず以下の共通のコンセプトと ID プロバイダーに関するガイドを確認し、その後、ワークロードで使用するプロダクトのセクションに進んでください。

• OpenAI API： OpenAI API での ワークロード ID の使用に進んでください。
• Codex： 管理ポータルとランタイムの セットアップ手順全体については、Codex での ワークロード ID の使用に従ってください。

管理者は、管理 API を使用して Codex のプロバイダーとルールを管理することもできます。ルールとライフサイクルの動作については、 Codex の フェデレーションルールの リファレンスを参照してください。

仕組み

ワークロードが接続する前に、管理者が次の 3 つを設定します。

1. ID プロバイダー は、信頼する外部の発行者と、 その署名付きトークンまたは証明書 ID の検証方法を OpenAI に指定します。
2. アクセスルール は、OpenAI が受け入れるトークン属性と、 ワークロードがどの OpenAI ID として動作できるかを定義します。OpenAI API の設定では、これをサービスアカウントマッピングと呼びます。 Codex の設定では、フェデレーションルールと呼びます。
3. OpenAI プリンシパル には、その結果としてアクセス権が付与されます。 OpenAI API の場合、プリンシパルは Platform のサービスアカウントです。Codex の場合は、 管理対象のワークスペース内の ChatGPT ユーザーまたはサービスアカウントです。

実行時には、次の処理が行われます。

1. ワークロードが短期間有効な OIDC JWT または SPIFFE JWT-SVID を受け取ります。OpenAI API のワークロードの場合は、X.509 証明書を提示する方法もあります。
2. ワークロードが、使用するプロダクトで必要な ID とともに、外部 ID を提示します。
3. OpenAI がトークンまたは証明書を検証し、設定されたマッピングまたはルールを評価します。
4. OpenAI が、マッピング先のプリンシパル用に短期間有効なアクセストークンを返します。

トークン交換によってプリンシパル、プロジェクト、ワークスペースのメンバーシップが作成されることはありません。これらのリソースは、管理者がセットアップ時に作成または選択します。

ID トークンの取得

ワークロードを実行する環境に対応したガイドを選択してください。

OpenAI は、このドキュメントに記載された構成で、 SPIFFE JWT-SVID を含む OIDC 互換の JWT サブジェクトトークンをサポートしています。OpenAI API を使用する場合、お使いの OIDC プロバイダーが一覧にないときは、 OpenAI サポートにお問い合わせください。Codex を使用する場合は、 OpenAI 管理ポータルで カスタム OIDC を選択してください。

各 OIDC プロバイダーのガイドでは、トークンの発行方法と確認方法を説明しています。 Codex を使用する場合は、トークンの発行手順のみを実施し、 Codex でのワークロード ID の使用に戻ってください。 各ガイドにある OpenAI のセットアップ手順と SDK の例は、OpenAI API を使用する場合に適用されます。 X.509 フェデレーションは、OpenAI API を使用する場合にのみ対応しています。

OpenAI API でのワークロード ID の使用

ワークロードが OpenAI API を直接呼び出す場合は、この手順を使用してください。組織のワークロード ID プロバイダーとサービスアカウントマッピングを管理する権限が必要です。

組織設定 > セキュリティ > ワークロード ID プロバイダーに移動します。 まずプロバイダーを作成し、 そのプロバイダーの詳細ページからサービスアカウントマッピングを設定します。

X.509 プロバイダー

X.509 プロバイダーは、組織の既存の相互 TLS 構成に照らして OpenAI が検証したクライアント証明書から、ワークロード ID の属性を導出します。証明書を保存したり、独立したトラストストアを維持したりすることはありません。

プロバイダーを作成する前に、 組織設定 > セキュリティ > 相互 TLSで、クライアント証明書の信頼の基点となる証明書を設定し、有効化します。 相互 TLS ガイドでは、権限、 証明書の要件、有効化の範囲、mTLS ホスト、証明書チェーンの動作、 CEL フィルター、ローテーションについて説明しています。

次に、X.509 プロバイダーを作成し、空でない openai.subject の値を 1 つ導出して、その ID をプロジェクトのサービスアカウントにマッピングします。サービスアカウントには、ワークロードに必要な権限のみを付与します。ワークロードは X.509 トークンエンドポイントに証明書を提示して、短期間有効なベアラートークンを取得します。その後、ベアラートークンと受け入れ可能なクライアント証明書を API の mTLS エンドポイントに送信します。

ダッシュボードでの操作からリクエストまでの手順全体については、X.509 証明書のセットアップガイドに従ってください。

OIDC ワークロード ID プロバイダーの構成

信頼する外部発行者ごとにワークロード ID プロバイダーを作成します。OpenAI API のワークロード ID は、OIDC JWT サブジェクトトークンをサポートしています。構成項目は次のとおりです。

カスタム OIDC ディスカバリーとアップロードした JWKS は併用できません。カスタムディスカバリーを有効にすると、JWKS のアップロードオプションは非表示になります。カスタムディスカバリー URL は公開 HTTPS URL である必要があり、認証情報、カスタムポート、クエリ、フラグメントを含めることはできません。

ダッシュボードに「 OIDC ディスカバリーにカスタム URL を使用 」が表示されない場合は、 標準の OIDC ディスカバリーを使用するか、代わりに「 アップロードした JWKS をトークン検証に使用」を有効にします。 ID プロバイダーが公開している公開鍵の JWKS を使用し、 プロバイダーが署名鍵をローテーションした際に更新してください。

トークンの発行者とディスカバリーホストが異なる場合は、 OIDC 発行者 URL に トークンの iss クレームを設定し、 カスタム OIDC ディスカバリー URL に プロバイダーのディスカバリードキュメントを公開するホストを設定します。OpenAI は引き続き、 構成された発行者と照合してトークンを検証します。カスタム URL が指定するのは、 ディスカバリーメタデータと署名用公開鍵の取得先だけです。

CEL によるトークンクレームの変換

属性変換には Common Expression Language（CEL）を使用します。 OpenAI は、 langdef.md で規定された標準の CEL 演算子をサポートしており、 ワークロード ID フェデレーション専用のカスタム関数は追加していません。各式には、 次の 1 つのルートオブジェクトが渡されます。

• assertion：検証済みの JWT クレームセット

ダッシュボードは openai. プレフィックスを自動的に付与します。 subject などのサフィックスと、assertion.sub などの式を入力します。 API は導出された属性を openai.subject として保存します。

12345678910[
  {
    "attribute": "openai.subject",
    "expression": "assertion.sub"
  },
  {
    "attribute": "openai.repository",
    "expression": "assertion.repository"
  }
]

CEL 言語仕様で定義された CEL 構文を使用してください。 たとえば、assertion.sub や assertion.repository などの式でクレームの値を読み取れます。サポートされていない構文や関数を使用すると、 マッピングの解決に失敗します。

12345678910[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  },
  {
    "attribute": "openai.production",
    "expression": "assertion.ref == \"refs/heads/main\""
  }
]

変換結果はスカラー値である必要があります。文字列、true または false、 整数、有限の数値が使用できます。配列、オブジェクト、null 値、 評価エラーは、マッピングの解決を失敗させます。OpenAI は、 スカラー値の変換結果を文字列に変換してから、マッピングの値と比較します。 たとえば、true は "true" に、7 は "7" に変換されます。

openai. で始まるマッピングキーは、属性変換の結果からのみ 解決されます。元のサブジェクトトークンのクレームに openai. プレフィックスが付いていても、 対応する変換を構成しない限り、マッピングの判定には影響しません。

JWKS と鍵のローテーションの管理

OpenAI は、ワークロード ID プロバイダーに構成された鍵の取得元を使用して、OIDC サブジェクトトークンを検証します。

• OIDC ディスカバリー： OpenAI は発行者の /.well-known/openid-configuration を取得した後、検出された jwks_uri から鍵を取得します。 OpenAI はディスカバリードキュメントとリモート JWKS ペイロードを 600 秒間キャッシュします。
• カスタム OIDC ディスカバリー： OpenAI は、 構成されたカスタムディスカバリーのベース URL から /.well-known/openid-configuration を取得し、 続いて検出された jwks_uri から鍵を取得します。トークンの iss クレームは、 引き続き OIDC 発行者 URL と一致する必要があります。
• 鍵が見つからない場合の更新： キャッシュされた JWKS にトークンの kid が見つからない場合、 OpenAI はトークンを拒否する前に JWKS を更新し、 再度検索します。
• アップロードした JWKS： 「 アップロードした JWKS をトークン検証に使用 」を 有効にすると、OpenAI はプロバイダーに保存されたアップロード済みの JWKS を使用し、 OIDC ディスカバリーやリモート JWKS の取得は行いません。プロバイダーの更新が トークン交換に反映されると、新しいトークン交換では保存済みの JWKS が使用されます。
• 鍵セット： JWKS には複数の公開鍵を含めることができます。各鍵には、 一意で空でない kid が必要です。

署名鍵をローテーションする際は、移行期間中、発行者の JWKS に新旧両方の公開鍵を 公開してください。これにより、古い鍵で署名されたトークンを引き続き使用しながら、 OpenAI が新しい鍵で署名されたトークンも受け入れられるようになります。アップロードした JWKS を使用する場合は、 新しい kid のトークンを発行する前にプロバイダーを更新してください。OpenAI は、 構成された JWKS に存在しない鍵で署名されたトークンを拒否します。

サービスアカウントマッピングの構成

サービスアカウントマッピングでは、OpenAI サービスアカウントのアクセストークンを発行できる外部 ID を定義します。

X.509 プロバイダーでは、マッピングキーに導出された openai.* 属性を使用します。 openai.subject の完全一致によるマッピングを推奨します。sub、aud、iss などの元の JWT クレームは、 OIDC プロバイダーにのみ適用されます。

構成項目は次のとおりです。

属性値は JSON のスカラー値である必要があります。文字列では、 repo:example/* のように、空でないプレフィックスに続く末尾のワイルドカードを 1 つ使用できます。 ワイルドカード単独での使用や、値の途中での使用はサポートされていません。

有効なワイルドカード値：

• repo:openai/*
• repository:my-org/*

サポートされていないワイルドカード値：

• *
• repo:*:prod
• repo/*/main

ダッシュボードでは、マッピングによる制限を「 権限」として表示します。 トークン交換のレスポンスでは、同じ制限を scope プロパティの OAuth スコープとして 返します。マッピングに管理 API のスコープを含めることはできず、 後続の API 呼び出しには通常の認可も引き続き適用されます。

マッピング解決の例

マッピングの解決は、OpenAI が外部 ID を検証した後に始まります。 OpenAI は、リクエストされた identity_provider_id と service_account_id に対応するマッピングを検索し、有効でないマッピングをスキップします。 各マッピングに必要な属性だけを評価し、設定されたすべての属性に一致する有効なマッピングが ちょうど 1 つある場合にのみ、トークンを発行します。

GitHub Actions のトークンに、次のクレームが含まれているとします。

1234567{
  "iss": "https://token.actions.githubusercontent.com",
  "aud": "https://api.openai.com/v1",
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "repository": "my-org/my-repo",
  "ref": "refs/heads/main"
}

プロバイダーは、次のように属性を導出できます。

123456[
  {
    "attribute": "openai.repository_ref",
    "expression": "assertion.repository + \"@\" + assertion.ref"
  }
]

サービスアカウントのマッピングでは、元の属性と導出した属性の両方を条件として指定できます。

3 つの値がすべて一致する必要があります。sub の値は末尾にワイルドカードを使用しているため、 repo:my-org/my-repo: で始まるすべての値に一致します。 openai.repository_ref キーの値は、同名の未加工のトークンクレームではなく、 属性変換の結果から解決されます。

トークン交換に一致する有効なマッピングが複数ある場合、OpenAI はその交換を拒否します。 OpenAI では、(provider, service account) のペアごとにマッピングが一意である必要があり、 異なるマッピングの権限が組み合わされることはありません。

ワークロードの接続

ID プロバイダーのガイドにある SDK の例を使用するか、 トークン交換エンドポイントを直接呼び出します。リクエストとレスポンスのフィールド、 認可の動作、現在の制限については、 ワークロード ID のトークン交換リファレンスを参照してください。

アクセストークンの更新

トークン交換を直接管理する場合は、トークンサービスからアプリケーションに認証情報を渡す際、access_token と expires_at を 一緒に渡してください。 expires_at フィールドは、UTC での有効期限の絶対時刻を 秒単位の Unix タイムスタンプで表します。時計のずれやリクエストのレイテンシを考慮し、 その時刻より前に更新するようスケジュールしてください。

expires_in フィールドは、トークンの発行時点からの有効期間を秒単位で表します。 たとえば、12:00 UTC に expires_in: 3600 で発行されたトークンは、 別のサービスが 12:05 UTC に受け取った場合でも 13:00 UTC に失効します。転送や処理にかかった時間によって トークンの有効期間が延びることはありません。詳しくは、レスポンスの フィールドを参照してください。

トークン交換ではリフレッシュトークンは返されません。更新するには、有効な外部 ID トークンまたはクライアント証明書を使用して、再度トークン交換を行ってください。

Codex でのワークロード ID の使用

管理対象の ChatGPT ワークスペースで、信頼された Codex の自動化を実行する場合は、この方法を使用します。Codex はワークロードを API プラットフォームのサービスアカウントではなく、ChatGPT のユーザーまたはサービスアカウントにマッピングします。

管理者向けの手順と実行時の手順全体については、Codex での ワークロード ID の使用を参照してください。 プロバイダーごとのトークン取得元、フェデレーションルール、 必須のトークンファイル設定、認証情報の優先順位、対応する Codex の インターフェース、ローテーション、検証について説明しています。監査で使用する帰属情報を任意で指定するために、 Codex は OPENAI_WORKLOAD_IDENTITY_CONTEXT を受け付けます。そのスキーマ、 プライバシー上の制限、監査の動作は、Codex のガイドで定義されています。

管理 API を使用すると、Codex のプロバイダーとルールを プログラムで管理できます。フェデレーションルールの リファレンスでは、 1 つのルールで複数の外部サブジェクトを受け入れながら、それらを 1 つの ChatGPT プリンシパルにマッピングする方法を説明しています。

接続のトラブルシューティング

OpenAI による ID トークンの拒否

トークンをローカルでデコードし、iss、aud、sub、exp、iat と プロバイダー固有のクレームを、プロバイダーの設定と照合してください。 本番環境のトークンをサードパーティーの JWT ツールに貼り付けないでください。

OpenAI API の場合は、トークンの属性を、選択したサービスアカウントのマッピングとも照合してください。Codex の場合は、選択したフェデレーションルールと照合してください。

OpenAI API のマッピングの不一致

リクエストで意図した ID プロバイダーとサービスアカウントの ID が使用されていること、 マッピングが有効であること、一致するマッピングがちょうど 1 つであることを確認してください。 エラーの詳しい分類については、トークン交換エラーのリファレンスを 参照してください。

Codex による構成不足の報告

Codex プロセスに、ワークロード ID に必要な 2 つの環境変数が両方とも設定されていること、 および OPENAI_IDENTITY_TOKEN_FILE に現在有効なトークンへの絶対パスが 指定されていることを確認してください。ファイルと親ディレクトリの権限も確認してください。

Codex による別の認証情報の使用

ワークロード ID に必要な 2 つの変数を両方とも Codex プロセスに読み込んでください。 どちらか一方の変数が存在すると、API キー、アクセストークン、 保存済みのログイン情報よりも WIF が優先されます。ダウンロードした構成を読み込んだ状態で新しいプロセスを起動し、 codex login status を再度実行してください。

セキュリティに関する推奨事項

• アプリケーションまたはワークロードごとに専用のプリンシパルを使用してください。
• 本番環境と非本番環境を分離してください。
• 広範なパターンよりも、クレームの完全一致を優先してください。
• ワークロードに必要なアクセス権のみを付与してください。
• アクセストークンの有効期間を短く設定してください。
• 使用していないプロバイダー、マッピング、ルールをレビューし、削除してください。
• トークン交換エラーや予期しないアクセスパターンをレビューしてください。

関連ドキュメント

• Codex でのワークロード ID の使用
• Codex のフェデレーションルールリファレンス
• 管理 API による Codex のワークロード ID の管理
• ワークロード ID のトークン交換リファレンス
• Codex の認証
• Codex の環境変数
• Codex の非対話モード