ワークロード 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 の利用を参照してください。

ルールの動作とライフサイクルについては、Codex フェデレーションルールのリファレンスを参照してください。

仕組み

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

1. ID プロバイダーでは、OpenAI が信頼する外部の発行者と、その発行者が署名したトークンまたは証明書に基づく ID の検証方法を指定します。
2. アクセスルールでは、OpenAI が受け入れるトークン属性と、ワークロードがどの OpenAI ID として動作できるかを指定します。OpenAI API の設定ではこれをサービスアカウントマッピング、Codex の設定ではフェデレーションルールと呼びます。
3. OpenAI プリンシパルは、こうしてアクセス権を付与される主体です。OpenAI API では API プラットフォームのサービスアカウント、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 管理ポータルで Custom OIDC を選択してください。

各 OIDC プロバイダーのガイドでは、トークンの発行方法と内容の確認方法を説明しています。Codex の場合は、トークンの発行手順だけを実行してから、Codex でのワークロード ID の利用に戻ってください。各ガイドの OpenAI 側の設定手順と SDK の例は、OpenAI API 向けです。X.509 フェデレーションを利用できるのは OpenAI API のみです。

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

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

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

X.509 プロバイダー

X.509 プロバイダーは、クライアント証明書からワークロード ID の属性を導出します。OpenAI は、組織の既存の相互 TLS 設定に基づいてこの証明書を検証します。プロバイダーは証明書を保存せず、個別のトラストストアも持ちません。

プロバイダーを作成する前に、組織設定 > セキュリティ > 相互 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 で公開されている必要があります。認証情報、カスタムポート、クエリ、フラグメントは含められません。

ダッシュボードに「OIDC ディスカバリーにカスタム URL を使用」が表示されない場合は、標準の OIDC ディスカバリーを使うか、「トークンの検証にアップロード済みの JWKS を使用」を有効にしてください。ID プロバイダーが公開している JWKS を使い、プロバイダーが署名鍵をローテーションしたら 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 の言語仕様で定義された構文を使ってください。たとえば、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 から鍵を取得します。ディスカバリードキュメントとリモートから取得した JWKS の内容は 600 秒間キャッシュされます。
• カスタム OIDC ディスカバリー： OpenAI は /.well-known/openid-configuration を設定済みのカスタムディスカバリーのベース URL から取得し、そこに記載された jwks_uri から鍵を取得します。この場合も、トークンの iss クレームは「OIDC 発行者 URL」と一致する必要があります。
• 鍵が見つからない場合の再取得： トークンの kid がキャッシュ済みの JWKS にない場合、OpenAI はトークンを拒否する前に JWKS を再取得し、もう一度鍵を検索します。
• アップロード済みの JWKS：「トークンの検証にアップロード済みの JWKS を使用」が有効な場合、OpenAI はプロバイダーにアップロードして保存した JWKS を使います。OIDC ディスカバリーやリモートからの JWKS の取得は行いません。プロバイダーの更新がトークン交換に反映されると、以降の交換には保存済みの JWKS が使われます。
• 鍵セット： 1 つの JWKS に複数の公開鍵を含められます。各鍵には、一意で空でない kid が必要です。

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

サービスアカウントマッピングの設定

サービスアカウントマッピングでは、どの外部 ID が OpenAI サービスアカウント用のアクセストークンの発行を受けられるかを定義します。

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 スコープとして示されます。マッピングに Admin 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 キーの値は属性変換の結果から取得します。トークンに含まれる同名のクレームをそのまま使うことはありません。

1 回の交換で複数の有効なマッピングが一致した場合、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 のユーザーまたはサービスアカウントです。

フェデレーションルールのリファレンスでは、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 の認証
• Codex の環境変数
• Codex の非対話モード