フェデレーションルールは、どの検証済みワークロード ID が単一の ChatGPT ユーザーまたはサービスアカウントとして動作できるかを決定します。OpenAI は、Codex プロセスが名前を指定したルールだけを評価します。一致するルールをすべてのルールから検索することはありません。
各ルールには対象となるプリンシパルが 1 つあり、上流の ID を 1 つ以上受け入れることができます。1 つのルールで複数のサブジェクトを受け入れるには、末尾にワイルドカードを付けたプレフィックス形式のサブジェクト、または CEL 条件を使用します。同じプリンシパルに対して複数のルールを作成することもできます。
セットアップ手順については、Codex での ワークロード ID の使用を参照してください。コードでルールを管理する方法については、 ワークロード ID の Admin APIを参照してください。
ルールの構成
| 構成要素 | 役割 |
|---|---|
| プロバイダー | OpenAI が信頼する発行者と署名鍵を定義します。 |
| ワークスペース | 付与されるアクセスを、管理対象の ChatGPT ワークスペース 1 つに制限します。 |
| プリンシパル | そのワークスペース内の既存のユーザーまたはサービスアカウントを 1 つ選択します。 |
| ID チェック | ルールを使用できる検証済み ID トークンを制限します。 |
| スコープ | 必要に応じて、既存の Codex OAuth スコープを絞り込みます。 |
| アクセストークンの有効期間 | OpenAI アクセストークンの有効期間を 60～3,600 秒に制限します。 |
交換を行う前に、プリンシパルとそのワークスペースメンバーシップが存在している必要があります。ワークロードが接続した際に、ルールがユーザー、サービスアカウント、メンバーシップを作成することはありません。
ID チェックの組み合わせ
ルールでは、次のチェックを使用できます。
| チェック | 動作 | 用途 |
|---|---|---|
| サブジェクト | sub の値との完全一致、または末尾に * を 1 つ付けたプレフィックスとの一致。 | 単一のワークロード ID、または管理されたサブジェクト名前空間。 |
| 受け入れるオーディエンス | 1～32 個のオーディエンス文字列。トークンには、そのうち少なくとも 1 つが含まれている必要があります。 | OpenAI 専用に発行されたトークン。 |
| 完全一致クレーム | トップレベルのスカラー型クレーム値を最大 32 個指定し、完全一致で照合します。 | 安定した文字列、数値、true/false 値、または null。 |
| CEL 条件 | assertion という名前の検証済みクレームマップを対象とするブール式。 | リスト、ネストされたクレーム、または許可する値の集合。 |
サブジェクト、完全一致クレーム、CEL のチェックを少なくとも 1 つ設定してください。受け入れるオーディエンスだけでは、ワークロードを識別できません。複数の種類のチェックを設定した場合は、すべてに合格する必要があります。
最初にプロバイダーの検証が行われます。ルールでは、プロバイダーの発行者、署名、有効期限、アサーションの有効期間、リプレイ、またはプロバイダーレベルの CEL チェックを上書きできません。
サブジェクトの照合
安定した単一の sub でワークロードを識別できる場合は、必ずサブジェクトの完全一致を使用してください。
repo:example-company/payments:environment:production末尾に * を 1 つ付けると、前方一致で照合します。
system:serviceaccount:production:codex-*ワイルドカードは最後の文字でなければならず、その前に空でないプレフィックスが必要です。
OpenAI は *、repo:*:production、repo/*/main を受け入れません。
より安定したクレームで特権を持つワークロードを区別できる場合は、対象範囲の広いプレフィックスを使用しないでください。たとえば、GitHub のルールでは、1 つの組織が所有するすべてのリポジトリではなく、特定のリポジトリ、ワークフローファイル、ref、または保護された環境に一致するように設定してください。
完全一致クレーム
完全一致クレームでは、トップレベルの JWT クレームを型変換せずに比較します。文字列は同じ文字列にのみ、ブール値は同じブール値にのみ一致し、数値は同じ数値に一致します。完全一致の値として、リストとオブジェクトはサポートされていません。
次に例を示します。
{
"repository": "example-company/payments",
"ref": "refs/heads/main",
"environment": "production"
}完全一致クレームのマップに sub を含めないでください。サブジェクトフィールドまたは CEL を使用してください。
ネストされたプロバイダークレームや、リストに値が含まれるかどうかの確認には CEL を使用してください。
CEL 条件
CEL 条件は、検証済みの JWT クレームマップ全体を assertion として受け取り、
true または false を返す必要があります。OpenAI は、ルール評価の動作を予測可能に保つため、
CEL の限定されたサブセットをサポートしています。
1 つのルールで、完全一致する複数のサブジェクトを許可する例です。
assertion.sub in [
"repo:example-company/payments:environment:production",
"repo:example-company/billing:environment:production"
]特定のリポジトリと、2 つの ref のいずれかを必須とする例です。
assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]ネストされたクレームや省略可能なクレームを読み取る例です。
has(assertion.environment) &&
assertion.environment == "production"サポートされているヘルパーには、has、size、contains、startsWith、
endsWith があります。正規表現による照合、
all や exists などのコレクション反復マクロ、任意の関数、assertion 以外の識別子は
サポートされていません。式は短く保ち、
同じポリシーを表現できる場合は完全一致チェックを優先してください。
クレームの欠落、サポートされていない演算、ブール値以外の結果、または評価エラーがあると、交換は拒否されます。
オーディエンスの照合
プロバイダーには、期待するオーディエンスを 1 つ設定できます。代わりに、ルールで
受け入れるオーディエンスを 1 つ以上設定することもできます。ルールにオーディエンスリストがある場合、
トークンの aud クレームの値が少なくとも 1 つ、そのリストに含まれている必要があります。
プロバイダーが対応している場合は、OpenAI 専用のオーディエンスを使用してください。SPIFFE JWT-SVID ルールでは、受け入れるオーディエンスの設定が必須です。OIDC ルールでも、プロバイダーレベルのオーディエンスが定義されていない場合は、設定が必要です。
オーディエンスの照合と ID チェックは、両方の条件を満たす必要があります。オーディエンスが一致していても、サブジェクト、完全一致クレーム、または CEL のチェックに合格しなければ、交換は許可されません。
対応するプリンシパルの数
1 つのルールは、必ず 1 つのプリンシパルに対応します。
many accepted external identities -> one federation rule -> one OpenAI principalこれにより、ワークロードのレプリカ、ジョブ、または許可されたサブジェクトが、同じユーザーまたはサービスアカウントとして動作できます。1 つのルールがクレームに基づいて異なるプリンシパルを選択することはできません。ワークロードごとに異なるプリンシパル、ワークスペース、スコープ、またはトークンの有効期間が必要な場合は、個別のルールを作成してください。
複数のルールで同じプリンシパルを対象にできます。ワークロードごとにライフサイクルを個別に管理したい場合や、監査時に各ワークロードの操作を明確に区別したい場合は、ルールを分けてください。
スコープと認可
ルールでは、発行されるアクセストークンの OAuth スコープを制限できます。対象のプリンシパルやワークスペースが持っていない権限を付与することはできません。
スコープを省略すると、OpenAI は標準の Codex スコープである openid、
profile、email、および Codex のローカルアクセスを使用します。
Admin API でスコープを設定する場合は、chatgpt.workspace.feature.allow-codex-local-access.access を含め、
サポートされているこの 4 つの値のみを使用してください。
まず、最小権限の原則に従ってプリンシパルとワークスペースの権限を選んでください。ルールのスコープは、認可の主要な境界ではなく、追加の制限として扱ってください。
トークンの有効期間
OpenAI アクセストークンの有効期間は、60 秒から 3,600 秒の範囲で設定してください。OpenAI は、次のうち短い方を使用します。
- 上流の ID トークンの残りの有効期間
- ルールに設定されたアクセストークンの有効期間
有効期間を短くすると、ポリシーの編集後も発行済みトークンが有効であり続ける時間を短縮できますが、交換の頻度は高くなります。ワークロードの要件に応じて別のバランスが必要な場合を除き、まずは 10 分に設定するのが実用的です。
リプレイ保護
プロバイダー単位のリプレイ保護には、JWT の jti クレームを使用します。
管理者が アサーションのリプレイを防止 を有効にしていて、トークンに空でない jti が含まれている場合、
OpenAI はアサーションの有効期限が切れるまで、そのプロバイダーに対してその jti を 1 回だけ受け入れます。
ワークロードは、交換のたびに、新しい jti を持つ新しいアサーションを事前に取得する必要があります。
これには、結果が不明な交換を再試行する場合も含まれます。
jti を持たないアサーションも引き続き使用できますが、リプレイ保護は適用されません。
jti の値が空、null、または文字列以外の場合は、検証に失敗します。
変更、無効化、アーカイブ
ID チェック、スコープ、トークンの有効期間に対する通常の編集は、新しい交換に適用されます。編集前に発行されたアクセストークンは、既存の TTL が切れるまで有効なままの場合があります。
ルールまたはプロバイダーを無効にすると、新しい交換がブロックされ、それを通じて発行された OpenAI アクセストークンが失効します。アーカイブにも同じ効果がありますが、元に戻すことはできません。発行者や JWKS の設定など、プロバイダーの信頼設定を変更すると、新しい信頼設定が有効になる前に発行済みトークンが失効します。
緊急停止や一時停止には無効化を使用してください。リソースをアーカイブするのは、そのリソースが不要になった場合だけにしてください。
上限
| リソース | 上限 |
|---|---|
| 組織あたりの未アーカイブのプロバイダー数 | 50 |
| プロバイダーあたりの未アーカイブのルール数 | 50 |
| ルールあたりの完全一致クレーム数 | 32 |
| ルールあたりの許可するオーディエンス数 | 重複しない 32 個の値 |
| サブジェクトの長さ | 4,096 バイト |
| 完全一致クレームのマップまたは CEL 条件 | 16 KiB |
| アクセストークンの有効期間 | 60 秒から 3,600 秒 |
発行者、鍵、リプレイ、ライフサイクルを個別に管理する必要がある信頼境界ごとに、プロバイダーを分けて作成してください。同じ信頼設定を共有しながら、異なるプリンシパルやアクセスポリシーを必要とするワークロードには、1 つのプロバイダー内で個別のルールを作成してください。