Referenz zu Föderationsregeln für Codex

Eine Föderationsregel legt fest, welche verifizierten Workload-Identitäten als ein bestimmtes ChatGPT-Benutzerkonto oder Dienstkonto handeln dürfen. OpenAI wertet nur die Regel aus, die der Codex-Prozess angibt. Es durchsucht nicht alle Regeln nach einer Übereinstimmung.

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

Die Setup-Anleitung findest du unter Workload-Identität mit Codex verwenden. Wie du Regeln per Code verwaltest, erfährst du in der Admin-API für Workload-Identität.

Regelmodell

Der Prinzipal und seine Workspace-Mitgliedschaft müssen vor dem Token-Austausch vorhanden sein. Eine Regel erstellt weder ein Benutzerkonto noch ein Dienstkonto oder eine Mitgliedschaft, wenn sich eine Workload verbindet.

Wie Identitätsprüfungen zusammenwirken

Eine Regel kann diese Prüfungen verwenden:

Lege mindestens eine Subject-Prüfung, eine Prüfung auf exakte Claims oder eine CEL-Prüfung fest. Eine akzeptierte Audience allein identifiziert keine Workload. Wenn du mehrere Prüfungsarten konfigurierst, müssen alle erfolgreich sein.

Zuerst erfolgen die Prüfungen auf Anbieterebene. Eine Regel kann die Prüfungen des Anbieters zu Aussteller, Signatur, Ablauf, Assertion-Laufzeit und wiederholter Verwendung sowie die CEL-Prüfungen auf Anbieterebene nicht außer Kraft setzen.

Subject-Abgleich

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

repo:example-company/payments:environment:production

Ein abschließendes * bewirkt einen Präfixabgleich:

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 oder repo/*/main.

Verwende kein weit gefasstes Präfix, wenn sich privilegierte Workloads durch einen stabileren Claim abgrenzen lassen. Eine GitHub-Regel sollte beispielsweise ein bestimmtes Repository, eine Ablaufdatei, eine Ref oder eine geschützte Umgebung abgleichen, statt alle Repositorys einer Organisation zu akzeptieren.

Exakte Claims

Bei exakten Claims werden JWT-Claims auf oberster Ebene verglichen, ohne ihre Typen umzuwandeln. Eine Zeichenfolge stimmt nur mit derselben Zeichenfolge überein, ein boolescher Wert nur mit demselben booleschen Wert und eine Zahl mit demselben numerischen Wert. Listen und Objekte werden als exakte Werte nicht unterstützt.

Zum Beispiel:

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

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

CEL-Bedingungen

CEL-Bedingungen erhalten die vollständige verifizierte JWT-Claim-Map als assertion und müssen true oder false zurückgeben. OpenAI unterstützt eine begrenzte Teilmenge von CEL, damit die Auswertung der Regeln vorhersehbar bleibt.

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

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

So verlangst du ein bestimmtes Repository und eine von zwei Refs:

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. Der Abgleich mit regulären Ausdrücken, Makros zum Iterieren über Sammlungen wie all oder exists, beliebige Funktionen und andere Bezeichner als assertion werden nicht unterstützt. Halte Ausdrücke kurz und bevorzuge exakte Prüfungen, wenn sich damit dieselbe Richtlinie abbilden lässt.

Ein fehlender Claim, eine nicht unterstützte Operation, ein nicht boolesches Ergebnis oder ein Auswertungsfehler führt zur Ablehnung des Token-Austauschs.

Audience-Abgleich

Der Anbieter kann eine erwartete Audience festlegen. Eine Regel kann stattdessen eine oder mehrere akzeptierte Audiences festlegen. Hat eine Regel eine Audience-Liste, muss mindestens ein Wert aus dem aud-Claim des Tokens in dieser Liste enthalten sein.

Verwende eine eigene Audience für OpenAI, wenn dein Anbieter dies unterstützt. Regeln für SPIFFE JWT-SVID müssen eine akzeptierte Audience festlegen. Eine OIDC-Regel muss ebenfalls eine festlegen, wenn der Anbieter keine Audience auf Anbieterebene definiert.

Audience-Abgleich und Identitätsprüfungen gelten gemeinsam. Eine passende Audience gleicht keine fehlgeschlagene Subject-Prüfung, Prüfung auf exakte Claims oder CEL-Prüfung aus.

Prinzipal-Kardinalität

Eine Regel ist genau einem Prinzipal zugeordnet:

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

Damit können Workload-Replikate, Jobs oder genehmigte Subjects als dasselbe Benutzerkonto oder Dienstkonto handeln. Eine Regel kann jedoch nicht anhand von Claims einen anderen Prinzipal auswählen. Erstelle separate Regeln, wenn Workloads unterschiedliche Prinzipale, Workspaces, Scopes oder Token-Laufzeiten benötigen.

Mehrere Regeln können denselben Prinzipal als Ziel haben. Verwende separate Regeln, wenn du den Lebenszyklus jeder Workload unabhängig steuern oder Aktivitäten im Audit eindeutiger zuordnen möchtest.

Scopes und Autorisierung

Die Regel kann die OAuth-Scopes im ausgestellten Zugriffstoken einschränken. Sie kann keine Berechtigungen erteilen, die der Zielprinzipal oder der Workspace nicht bereits hat.

Wenn du keine Scopes angibst, verwendet OpenAI die standardmäßigen Codex-Scopes: openid, profile, email und lokalen Codex-Zugriff. Wenn du Scopes über die Admin API festlegst, gib chatgpt.workspace.feature.allow-codex-local-access.access an und verwende nur diese vier unterstützten Werte.

Wähle zunächst einen Prinzipal und Workspace-Berechtigungen mit den geringstmöglichen Zugriffsrechten. Betrachte die Scopes einer Regel als zusätzliche Einschränkung, nicht als primäre Autorisierungsgrenze.

Token-Gültigkeitsdauer

Lege die Gültigkeitsdauer des OpenAI-Zugriffstokens auf 60 bis 3.600 Sekunden fest. OpenAI verwendet die kürzere der folgenden Zeitspannen:

• Die verbleibende Gültigkeitsdauer des vorgelagerten Identitätstokens.
• Die in der Regel konfigurierte Gültigkeitsdauer für Zugriffstoken.

Kürzere Gültigkeitsdauern verkürzen den Zeitraum, in dem ein ausgestelltes Token nach einer Richtlinienänderung noch gültig sein kann. Dafür muss der Tokenaustausch häufiger erfolgen. Zehn Minuten sind ein praktikabler Ausgangspunkt, sofern deine Workload keine andere Abwägung erfordert.

Replay-Schutz

Der Replay-Schutz auf Anbieterebene verwendet den JWT-Claim jti. Wenn die Administration Wiederverwendung von Assertions verhindern aktiviert und das Token einen nicht leeren jti-Wert enthält, akzeptiert OpenAI diesen jti-Wert für diesen Anbieter bis zum Ablauf der Assertion nur einmal.

Die Workload muss vor jedem Tokenaustausch eine neue Assertion mit einem neuen jti-Wert abrufen. Das gilt auch für Wiederholungsversuche nach einem Austausch mit unbekanntem Ergebnis. Assertions ohne jti bleiben verwendbar, erhalten aber keinen Replay-Schutz. Leere jti-Werte, null-Werte oder Werte, die keine Zeichenfolgen sind, bestehen die Validierung nicht.

Änderungen, Deaktivierung und Archivierung

Reguläre Änderungen an Identitätsprüfungen, Scopes oder der Token-Gültigkeitsdauer gelten für neue Tokenaustauschvorgänge. Zugriffstoken, die vor der Änderung ausgestellt wurden, können bis zum Ende ihrer bisherigen Gültigkeitsdauer (TTL) gültig bleiben.

Wenn du eine Regel oder einen Anbieter deaktivierst, werden neue Tokenaustauschvorgänge blockiert und darüber ausgestellte OpenAI-Zugriffstoken widerrufen. Eine Archivierung hat dieselbe Wirkung und lässt sich nicht rückgängig machen. Wenn du die Vertrauenskonfiguration eines Anbieters änderst, etwa die Aussteller- oder JWKS-Einstellungen, werden ausgestellte Token widerrufen, bevor die neue Vertrauenskonfiguration aktiv wird.

Verwende die Deaktivierung für einen Notstopp oder eine vorübergehende Pause. Archiviere eine Ressource nur, wenn du sie nicht mehr benötigst.

Limits

Erstelle separate Anbieter für Vertrauensbereiche, deren Aussteller, Schlüssel, Replay-Schutz oder Lebenszyklus unabhängig gesteuert werden müssen. Erstelle unter einem Anbieter separate Regeln für Workloads, die dieselbe Vertrauensgrundlage haben, aber unterschiedliche Prinzipale oder Zugriffsrichtlinien benötigen.