Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Referenz zu Föderationsregeln für Codex

Ordne Claims externer Workloads einem ChatGPT-Prinzipal zu und begrenze den Zugriff durch eine Richtlinie.

Eine Föderationsregel legt fest, welche verifizierten Workload-Identitäten als ein bestimmtes ChatGPT-Benutzerkonto oder Dienstkonto agieren dürfen. OpenAI wertet ausschließlich die Regel aus, die der Codex-Prozess angibt. OpenAI durchsucht die übrigen Regeln nicht nach einem Treffer.

Jede Regel hat genau einen Zielprinzipal und kann eine oder mehrere Identitäten des vorgelagerten Providers akzeptieren. Um mehrere Subjects mit einer Regel zuzulassen, verwende ein Subject-Präfix mit abschließendem Platzhalter oder eine CEL-Bedingung. Du kannst auch mehrere Regeln für denselben Prinzipal erstellen.

Aufbau einer Regel

Bestandteil Zweck
Provider Legt fest, welchem Aussteller und welchen Signaturschlüsseln OpenAI vertraut.
Workspace Beschränkt den Zugriff auf einen verwalteten ChatGPT-Workspace.
Prinzipal Bestimmt ein vorhandenes Benutzerkonto oder Dienstkonto in diesem Workspace.
Identitätsprüfungen Legen fest, für welche verifizierten Identitätstoken die Regel verwendet werden darf.
Scopes Schränken bei Bedarf die vorhandenen OAuth-Scopes für Codex weiter ein.
Laufzeit des Zugriffstokens Legt fest, wie lange das OpenAI-Zugriffstoken gültig ist (60–3.600 Sekunden).

Der Prinzipal muss vor dem Token-Austausch bereits existieren und Mitglied des Workspaces sein. Wenn sich ein Workload verbindet, legt die Regel weder ein Benutzerkonto noch ein Dienstkonto oder eine Mitgliedschaft an.

Zusammenspiel der Identitätsprüfungen

Eine Regel kann die folgenden Prüfungen verwenden:

Prüfung Funktionsweise Einsatzbereich
Subject Exakter sub-Wert oder ein Präfix mit einem einzelnen * am Ende. Eine einzelne Workload-Identität oder ein kontrollierter Subject-Namensraum.
Akzeptierte Audiences 1–32 Audience-Zeichenfolgen. Das Token muss mindestens eine davon enthalten. Speziell für OpenAI ausgestellte Token.
Exakte Claims Exakter Abgleich von bis zu 32 skalaren Claim-Werten auf oberster Ebene. Stabile Zeichenfolgen, Zahlen, boolesche Werte oder null.
CEL-Bedingung Ein boolescher Ausdruck, der die verifizierten Claims in assertion auswertet. Listen, verschachtelte Claims oder eine Menge zulässiger Werte.

Konfiguriere mindestens eine Prüfung für das Subject, für exakte Claims oder per CEL. Eine akzeptierte Audience allein identifiziert keinen Workload. Wenn du mehrere Prüfungsarten konfigurierst, müssen alle Prüfungen erfolgreich sein.

Zuerst erfolgen die Prüfungen auf Provider-Ebene. Eine Regel kann keine dieser Prüfungen außer Kraft setzen. Das gilt für Aussteller, Signatur, Ablaufzeitpunkt und Laufzeit der Assertion ebenso wie für Replay-Schutz und CEL-Prüfungen des Providers.

Subject-Abgleich

Verwende ein exaktes Subject, wenn ein stabiler sub-Wert den Workload identifiziert:

repo:example-company/payments:environment:production

Mit einem einzelnen * am Ende prüft die Regel, ob das Subject mit dem angegebenen Präfix beginnt:

system:serviceaccount:production:codex-*

Der Platzhalter muss das letzte Zeichen sein und auf ein nicht leeres Präfix folgen. OpenAI akzeptiert weder * noch repo:*:production noch repo/*/main.

Verwende kein zu allgemeines Präfix, wenn sich privilegierte Workloads anhand eines stabileren Claims unterscheiden lassen. Eine GitHub-Regel sollte beispielsweise ein bestimmtes Repository, eine Workflow-Datei, eine Ref oder eine geschützte Umgebung prüfen, statt alle Repositorys einer Organisation zuzulassen.

Exakte Claims

Bei exakten Claims vergleicht die Regel JWT-Claims auf oberster Ebene, ohne deren Typ zu konvertieren. Eine Zeichenfolge stimmt nur mit derselben Zeichenfolge überein, ein boolescher Wert nur mit demselben booleschen Wert und eine Zahl nur mit demselben Zahlenwert. Listen und Objekte sind als exakte Werte nicht zulässig.

Beispiel:

{
  "repository": "example-company/payments",
  "ref": "refs/heads/main",
  "environment": "production"
}

Nimm sub nicht in die Map für exakte Claims auf. Verwende dafür das Subject-Feld oder CEL. Verwende CEL auch, um verschachtelte Provider-Claims zu prüfen oder festzustellen, ob ein Wert in einer Liste enthalten ist.

CEL-Bedingungen

CEL-Bedingungen erhalten die vollständige Map der verifizierten JWT-Claims als assertion und müssen true oder false zurückgeben. OpenAI unterstützt einen begrenzten Teil des CEL-Funktionsumfangs, damit die Regelauswertung vorhersehbar bleibt.

So lässt du mehrere exakt angegebene Subjects in einer Regel zu:

assertion.sub in [
  "repo:example-company/payments:environment:production",
  "repo:example-company/billing:environment:production"
]

So setzt du ein bestimmtes Repository und eine von zwei Refs voraus:

assertion.repository == "example-company/payments" &&
assertion.ref in ["refs/heads/main", "refs/heads/release"]

So liest du einen verschachtelten oder optionalen Claim:

has(assertion.environment) &&
assertion.environment == "production"

Zu den unterstützten Hilfsfunktionen gehören has, size, contains, startsWith und endsWith. OpenAI unterstützt weder den Abgleich mit regulären Ausdrücken noch Makros zum Durchlaufen von Sammlungen wie all oder exists. Beliebige Funktionen und andere Bezeichner als assertion sind ebenfalls nicht zulässig. Halte Ausdrücke kurz und bevorzuge exakte Prüfungen, wenn sie dieselbe Richtlinie abbilden können.

Fehlt ein Claim, wird eine Operation nicht unterstützt, ist das Ergebnis kein boolescher Wert oder tritt bei der Auswertung ein Fehler auf, lehnt OpenAI den Token-Austausch ab.

Audience-Abgleich

Der Provider kann eine erwartete Audience festlegen. Alternativ kannst du in einer Regel eine oder mehrere akzeptierte Audiences angeben. Enthält die Regel eine Audience-Liste, muss mindestens ein Wert aus dem aud-Claim des Tokens in dieser Liste stehen.

Verwende eine eigene Audience für OpenAI, wenn dein Provider das unterstützt. Für SPIFFE-JWT-SVID-Regeln musst du eine akzeptierte Audience angeben. Bei einer OIDC-Regel ist das ebenfalls erforderlich, wenn auf Provider-Ebene keine Audience festgelegt ist.

Der Audience-Abgleich und die Identitätsprüfungen müssen jeweils erfolgreich sein. Eine passende Audience gleicht eine fehlgeschlagene Prüfung des Subjects, der exakten Claims oder der CEL-Bedingung nicht aus.

Zuordnung zum Prinzipal

Jede Regel verweist auf genau einen Prinzipal:

many accepted external identities -> one federation rule -> one OpenAI principal

So können Workload-Replikate, Jobs oder zugelassene Subjects als dasselbe Benutzerkonto oder Dienstkonto agieren. Eine einzelne Regel kann nicht anhand von Claims zwischen verschiedenen Prinzipalen wählen. Erstelle separate Regeln, wenn Workloads unterschiedliche Prinzipale, Workspaces, Scopes oder Token-Laufzeiten benötigen.

Mehrere Regeln können auf denselben Prinzipal verweisen. Verwende separate Regeln, wenn du den Lebenszyklus für jeden Workload unabhängig steuern oder beim Audit Aktivitäten eindeutiger dem jeweiligen Workload zuordnen möchtest.

Scopes und Autorisierung

Die Regel kann die OAuth-Scopes im ausgestellten Zugriffstoken einschränken. Sie kann keine Berechtigungen gewähren, über die der Zielprinzipal oder der Workspace nicht bereits verfügt.

Wenn du keine Scopes angibst, verwendet OpenAI die Standard-Scopes für Codex: openid, profile, email und den lokalen Codex-Zugriff. Wenn du Scopes über die Admin-API festlegst, gib chatgpt.workspace.feature.allow-codex-local-access.access an und verwende ausschließlich Werte aus diesen vier unterstützten Scopes.

Wähle zuerst einen Prinzipal und Workspace-Berechtigungen nach dem Prinzip der geringsten Rechte. Verwende die Scopes der Regel als zusätzliche Einschränkung. Die eigentliche Zugriffsgrenze bilden die Berechtigungen des Prinzipals und des Workspaces.

Token-Laufzeit

Lege für das OpenAI-Zugriffstoken eine Laufzeit von 60 bis 3.600 Sekunden fest. OpenAI verwendet die kürzere der beiden folgenden Laufzeiten:

  • Die verbleibende Laufzeit des Identitätstokens vom vorgelagerten Provider.
  • Die in der Regel konfigurierte Laufzeit des Zugriffstokens.

Bei kürzeren Laufzeiten bleiben bereits ausgestellte Token nach einer Richtlinienänderung höchstens noch für kurze Zeit gültig. Dafür muss der Workload häufiger Token austauschen. Eine Laufzeit von 10 Minuten ist ein praktischer Ausgangspunkt, sofern dein Workload keine andere Abwägung erfordert.

Replay-Schutz

Der Replay-Schutz auf Provider-Ebene nutzt den JWT-Claim jti. Wenn jemand mit Administrationsrechten die Option „Wiederverwendung von Assertions verhindern“ aktiviert und das Token einen nicht leeren jti-Wert enthält, akzeptiert OpenAI diesen jti-Wert für den betreffenden Provider bis zum Ablauf der Assertion nur einmal.

Der Workload muss vor jedem Token-Austausch eine neue Assertion mit einem neuen jti-Wert beziehen. Das gilt auch für Wiederholungsversuche, wenn das Ergebnis des vorherigen Austauschs unbekannt ist. Assertions ohne jti bleiben verwendbar, haben aber keinen Replay-Schutz. Ist der jti-Wert leer, null oder keine Zeichenfolge, schlägt die Validierung fehl.

Änderungen, Deaktivierung und Archivierung

Reguläre Änderungen an Identitätsprüfungen, Scopes oder der Token-Laufzeit gelten für neue Austauschvorgänge. Zugriffstoken, die vor der Änderung ausgestellt wurden, können bis zum Ende ihrer ursprünglichen Laufzeit gültig bleiben.

Wenn du eine Regel oder einen Provider deaktivierst, blockiert OpenAI neue Austauschvorgänge und widerruft die darüber ausgestellten OpenAI-Zugriffstoken. Eine Archivierung hat dieselbe Wirkung und lässt sich nicht rückgängig machen. Änderst du die Vertrauenseinstellungen des Providers, etwa den Aussteller oder die JWKS-Einstellungen, widerruft OpenAI bereits ausgestellte Token, bevor die neue Konfiguration wirksam wird.

Deaktiviere die Ressource, wenn du den Zugriff im Notfall stoppen oder vorübergehend aussetzen möchtest. Archiviere sie erst, wenn du sie nicht mehr benötigst.

Grenzwerte

Ressource Grenzwert
Nicht archivierte Provider pro Organisation 50
Nicht archivierte Regeln pro Provider 50
Exakte Claims pro Regel 32
Akzeptierte Audiences pro Regel 32 unterschiedliche Werte
Länge des Subjects 4.096 Byte
Map für exakte Claims oder CEL-Bedingung 16 KiB
Laufzeit des Zugriffstokens 60–3.600 Sekunden

Erstelle separate Provider für Vertrauensbereiche, in denen du Aussteller, Schlüssel, Replay-Schutz oder Lebenszyklus unabhängig verwalten musst. Erstelle separate Regeln unter demselben Provider, wenn Workloads dieselben Vertrauenseinstellungen nutzen, aber unterschiedliche Prinzipale oder Zugriffsrichtlinien benötigen.