Codex フェデレーションルールのリファレンス

フェデレーションルールは、どの検証済みワークロード ID が単一の ChatGPT ユーザーまたはサービスアカウントとして動作できるかを決定します。OpenAI は、Codex プロセスが名前を指定したルールだけを評価します。一致するルールをすべてのルールから検索することはありません。

各ルールには対象となるプリンシパルが 1 つあり、上流の ID を 1 つ以上受け入れることができます。1 つのルールで複数のサブジェクトを受け入れるには、末尾にワイルドカードを付けたプレフィックス形式のサブジェクト、または CEL 条件を使用します。同じプリンシパルに対して複数のルールを作成することもできます。

セットアップ手順については、Codex での ワークロード ID の使用を参照してください。コードでルールを管理する方法については、 ワークロード ID の Admin APIを参照してください。

ルールの構成

交換を行う前に、プリンシパルとそのワークスペースメンバーシップが存在している必要があります。ワークロードが接続した際に、ルールがユーザー、サービスアカウント、メンバーシップを作成することはありません。

ID チェックの組み合わせ

ルールでは、次のチェックを使用できます。

サブジェクト、完全一致クレーム、CEL のチェックを少なくとも 1 つ設定してください。受け入れるオーディエンスだけでは、ワークロードを識別できません。複数の種類のチェックを設定した場合は、すべてに合格する必要があります。

最初にプロバイダーの検証が行われます。ルールでは、プロバイダーの発行者、署名、有効期限、アサーションの有効期間、リプレイ、またはプロバイダーレベルの CEL チェックを上書きできません。

サブジェクトの照合

安定した単一の sub でワークロードを識別できる場合は、必ずサブジェクトの完全一致を使用してください。

repo:example-company/payments:environment:production

末尾に * を 1 つ付けると、前方一致で照合します。

system:serviceaccount:production:codex-*

ワイルドカードは最後の文字でなければならず、その前に空でないプレフィックスが必要です。 OpenAI は *、repo:*:production、repo/*/main を受け入れません。

より安定したクレームで特権を持つワークロードを区別できる場合は、対象範囲の広いプレフィックスを使用しないでください。たとえば、GitHub のルールでは、1 つの組織が所有するすべてのリポジトリではなく、特定のリポジトリ、ワークフローファイル、ref、または保護された環境に一致するように設定してください。

完全一致クレーム

完全一致クレームでは、トップレベルの JWT クレームを型変換せずに比較します。文字列は同じ文字列にのみ、ブール値は同じブール値にのみ一致し、数値は同じ数値に一致します。完全一致の値として、リストとオブジェクトはサポートされていません。

次に例を示します。

12345{
  "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 の設定など、プロバイダーの信頼設定を変更すると、新しい信頼設定が有効になる前に発行済みトークンが失効します。

緊急停止や一時停止には無効化を使用してください。リソースをアーカイブするのは、そのリソースが不要になった場合だけにしてください。

上限

発行者、鍵、リプレイ、ライフサイクルを個別に管理する必要がある信頼境界ごとに、プロバイダーを分けて作成してください。同じ信頼設定を共有しながら、異なるプリンシパルやアクセスポリシーを必要とするワークロードには、1 つのプロバイダー内で個別のルールを作成してください。