Mit der Identitätsföderation kann ein vertrauenswürdiger Workload seine vorhandene Identität verwenden. So muss er weder einen OpenAI-API-Schlüssel noch ChatGPT-Zugangsdaten speichern. Der Workload übermittelt ein kurzlebiges Token deines Identitätsanbieters. OpenAI tauscht es gegen ein kurzlebiges OpenAI-Zugriffstoken ein.
Workloads für die OpenAI API können über die Identitätsföderation mit X.509 auch eine verifizierte Zertifikatsidentität gegen ein Zugriffstoken eintauschen.
Du kannst die Identitätsföderation für Workloads mit der OpenAI API oder mit Codex verwenden:
| OpenAI API | Codex | |
|---|---|---|
| OpenAI-Identität | Ein Dienstkonto in einem Projekt der API-Plattform | Ein Benutzer- oder Dienstkonto in einem verwalteten ChatGPT-Workspace |
| Wo die Administration die Föderation einrichtet | OpenAI Platform | OpenAI Admin Portal |
| Wie der Workload die Verbindung herstellt | Über ein OpenAI-SDK oder den Endpunkt für den Tokenaustausch | Über Codex-Umgebungsvariablen und eine Datei mit dem Identitätstoken |
| Welche Zugriffsrechte das Token gewährt | Zugriff auf die APIs im Rahmen der Berechtigungen des zugeordneten Dienstkontos | Zugriff auf Codex im Umfang der Zugriffsrechte des zugeordneten Workspace-Prinzipals |
Beide Varianten verwenden dasselbe Vertrauensmodell. Sie unterscheiden sich in der Verwaltung und der Laufzeitkonfiguration. Lies zuerst die gemeinsamen Grundlagen und die Hinweise zu Identitätsanbietern. Folge dann dem Abschnitt für das Produkt, das dein Workload nutzt.
- OpenAI API: Fahre mit Workload-Identität mit der OpenAI API verwenden fort.
- Codex: Lies Workload-Identität mit Codex verwenden.
Wie die Regeln funktionieren und welchen Lebenszyklus sie durchlaufen, erfährst du in der Referenz zu Codex-Föderationsregeln.
So funktioniert die Föderation
Bevor der Workload eine Verbindung herstellt, konfiguriert die Administration drei Dinge:
- Der Identitätsanbieter legt fest, welchem externen Aussteller OpenAI vertraut und wie OpenAI dessen signierte Tokens oder Zertifikatsidentitäten überprüft.
- Eine Zugriffsregel legt fest, welche Tokenattribute OpenAI akzeptiert und unter welcher OpenAI-Identität der Workload handeln darf. In der Konfiguration der OpenAI API heißt diese Regel Dienstkontozuordnung, bei Codex Föderationsregel.
- Der OpenAI-Prinzipal erhält die daraus resultierenden Zugriffsrechte. Bei der OpenAI API ist der Prinzipal ein Dienstkonto der API-Plattform. Bei Codex ist es ein ChatGPT-Benutzerkonto oder ein Dienstkonto in einem verwalteten Workspace.
Zur Laufzeit läuft der Austausch so ab:
- Der Workload erhält ein kurzlebiges OIDC-JWT oder SPIFFE JWT-SVID. Ein Workload für die OpenAI API kann alternativ ein X.509-Zertifikat vorlegen.
- Der Workload übermittelt seine externe Identität zusammen mit den IDs, die das jeweilige Produkt benötigt.
- OpenAI überprüft das Token oder Zertifikat und wertet anschließend die konfigurierte Zuordnung oder Regel aus.
- OpenAI gibt ein kurzlebiges Zugriffstoken für den zugeordneten Prinzipal zurück.
Beim Tokenaustausch werden keine Prinzipale, Projekte oder Workspace-Mitgliedschaften erstellt. Die Administration legt diese Ressourcen beim Setup an oder wählt vorhandene Ressourcen aus.
Identitätstoken beziehen
Wähle die Anleitung für die Umgebung, in der dein Workload läuft:
Richte den zertifikatsbasierten Tokenaustausch für Workloads ein, die die OpenAI API nutzen.
Verwende projizierte Dienstkontotokens in selbst verwalteten Clustern.
Verwende die ausgehende Identitätsföderation oder projizierte Tokens von Amazon EKS.
Verwende Tokens für verwaltete Identitäten oder projizierte Dienstkontotokens von AKS.
Verwende Identitätstokens vom Metadatenserver oder projizierte Dienstkontotokens von GKE.
Verwende Tokens für Instanzprinzipale aus einer Oracle-Identitätsdomäne.
Verwende OIDC-Tokens in Workflows für die kontinuierliche Integration.
Verwende SPIFFE JWT-SVIDs, die SPIRE oder ein kompatibler Anbieter ausstellt.
Verwende SPIFFE JWT-SVIDs, die Idira Secure Workload Access ausstellt.
OpenAI unterstützt in den dokumentierten Konfigurationen OIDC-kompatible JWTs als Subject-Tokens, einschließlich SPIFFE JWT-SVIDs. Wenn du die OpenAI API verwendest und dein OIDC-Anbieter nicht aufgeführt ist, wende dich an den OpenAI-Support. Für Codex wählst du im OpenAI Admin Portal Custom OIDC.
Jede Anleitung zu einem OIDC-Anbieter erklärt, wie du ein Token ausstellst und prüfst. Führe für Codex nur die Schritte zur Tokenausstellung aus und kehre dann zum Abschnitt Workload-Identität mit Codex verwenden zurück. Das OpenAI-Setup und die SDK-Beispiele in diesen Anleitungen gelten für die OpenAI API. Die X.509-Föderation unterstützt ausschließlich die OpenAI API.
Workload-Identität mit der OpenAI API verwenden
Verwende diese Variante, wenn dein Workload die OpenAI API direkt aufruft. Du benötigst die Berechtigung, Identitätsanbieter für Workloads und Dienstkontozuordnungen für die Organisation zu verwalten.
Öffne Organisationseinstellungen > Sicherheit > Identitätsanbieter für Workloads. Erstelle zuerst den Anbieter. Konfiguriere dann auf seiner Detailseite die Dienstkontozuordnungen.
X.509-Anbieter
Ein X.509-Anbieter leitet die Identitätsattribute des Workloads aus einem Clientzertifikat ab. OpenAI überprüft das Zertifikat anhand der vorhandenen mTLS-Konfiguration deiner Organisation. Der Anbieter speichert keine Zertifikate und verwaltet keinen separaten Vertrauensspeicher.
Bevor du den Anbieter erstellst, konfiguriere und aktiviere unter Organisationseinstellungen > Sicherheit > Mutual TLS das vertrauenswürdige Zertifikat, das als Vertrauensanker für dein Clientzertifikat dient. Die Anleitung zu Mutual TLS erläutert die Berechtigungen, Zertifikatsanforderungen, den Geltungsbereich der Aktivierung, mTLS-Hosts, den Umgang mit Zertifikatsketten, CEL-Filter und die Zertifikatsrotation.
Erstelle anschließend den X.509-Anbieter und leite einen einzelnen, nicht leeren Wert für openai.subject ab. Ordne diese Identität einem Projektdienstkonto zu, das nur die für den Workload erforderlichen Berechtigungen hat. Der Workload legt sein Zertifikat am X.509-Tokenendpunkt vor und erhält ein kurzlebiges Bearer-Token. Anschließend sendet er das Bearer-Token und ein akzeptiertes Clientzertifikat an den mTLS-Endpunkt der API.
Die Setup-Anleitung für X.509-Zertifikate beschreibt alle Schritte im Dashboard und den vollständigen Ablauf der Anfragen.
OIDC-Identitätsanbieter für Workloads konfigurieren
Erstelle für jeden externen Aussteller, dem du vertraust, einen Identitätsanbieter für Workloads. Für Workload-Identitäten unterstützt die OpenAI API OIDC-JWTs als Subject-Tokens. Die Konfiguration umfasst folgende Optionen:
| Option | Beschreibung |
|---|---|
| Name | Ein innerhalb deiner Organisation eindeutiger Name für den Identitätsanbieter für Workloads. |
| URL des OIDC-Ausstellers | Die erwartete URL des OIDC-Ausstellers. Beim Vergleich der Aussteller-URLs bleibt ein abschließender Schrägstrich unberücksichtigt. |
| Zielgruppe | Der erwartete aud-Claim im externen Subject-Token. |
| Beschreibung | Optionale Beschreibung des Identitätsanbieters für Workloads. |
| Benutzerdefinierte URL für die OIDC-Discovery verwenden | Ist diese Option aktiviert, ruft OpenAI die OIDC-Discovery-Metadaten von einer öffentlichen HTTPS-URL ab. Sie kann von der URL des Tokenausstellers abweichen. |
| Benutzerdefinierte OIDC-Discovery-URL | Die Basis-URL für die Discovery oder die vollständige URL für /.well-known/openid-configuration, die OpenAI bei aktivierter benutzerdefinierter Discovery verwendet. |
| Hochgeladenes JWKS zur Tokenprüfung verwenden | Ist diese Option aktiviert, überprüft OpenAI Tokens anhand eines hochgeladenen JWKS, statt Schlüssel über die OIDC-Discovery abzurufen. |
| JWKS-JSON | Das hochgeladene öffentliche JWKS-Objekt, das OpenAI bei aktivierter Prüfung mit hochgeladenem JWKS verwendet. Das JWKS muss ein nicht leeres keys-Array enthalten und darf kein privates Schlüsselmaterial enthalten. |
| Attributtransformationen | Optionale CEL-Ausdrücke, die aus Token-Claims benutzerdefinierte openai.*-Attribute für die Dienstkontozuordnung ableiten. |
Benutzerdefinierte OIDC-Discovery und hochgeladenes JWKS schließen sich gegenseitig aus. Wenn du die benutzerdefinierte Discovery aktivierst, blendet das Dashboard die Option für das hochgeladene JWKS aus. Die benutzerdefinierte Discovery-URL muss öffentlich über HTTPS erreichbar sein. Sie darf weder Zugangsdaten noch einen benutzerdefinierten Port, einen Query-String oder ein Fragment enthalten.
Wenn Benutzerdefinierte URL für die OIDC-Discovery verwenden in deinem Dashboard fehlt, verwende die standardmäßige OIDC-Discovery oder aktiviere Hochgeladenes JWKS zur Tokenprüfung verwenden. Verwende das öffentliche JWKS deines Identitätsanbieters und aktualisiere es, wenn der Anbieter seine Signaturschlüssel wechselt.
Wenn sich Tokenaussteller und Discovery-Host unterscheiden, setze die URL des OIDC-Ausstellers auf den Wert des iss-Claims im Token. Gib als Benutzerdefinierte OIDC-Discovery-URL den Host an, auf dem der Anbieter sein Discovery-Dokument veröffentlicht. OpenAI prüft das Token weiterhin anhand des konfigurierten Ausstellers. Die benutzerdefinierte URL bestimmt lediglich, wo OpenAI Discovery-Metadaten und öffentliche Signaturschlüssel abruft.
Token-Claims mit CEL transformieren
Attributtransformationen verwenden die Common Expression Language (CEL). OpenAI unterstützt die in langdef.md definierten CEL-Standardoperatoren. Zusätzliche Funktionen speziell für die Identitätsföderation gibt es nicht. Jeder Ausdruck erhält ein einziges Wurzelobjekt:
assertion: die verifizierten Claims des JWT.
Das Dashboard ergänzt automatisch das Präfix openai.. Gib das Suffix ein, zum Beispiel subject, und einen Ausdruck wie assertion.sub. Die API speichert das abgeleitete Attribut als openai.subject.
[
{
"attribute": "openai.subject",
"expression": "assertion.sub"
},
{
"attribute": "openai.repository",
"expression": "assertion.repository"
}
]
Verwende die Syntax aus der CEL-Sprachspezifikation. Mit Ausdrücken wie assertion.sub oder assertion.repository kannst du beispielsweise Claim-Werte auslesen. Verwendest du nicht unterstützte Syntax oder Funktionen, schlägt die Ermittlung der Zuordnung fehl.
[
{
"attribute": "openai.repository_ref",
"expression": "assertion.repository + \"@\" + assertion.ref"
},
{
"attribute": "openai.production",
"expression": "assertion.ref == \"refs/heads/main\""
}
]
Transformationen müssen skalare Werte liefern: Zeichenfolgen, die booleschen Werte true oder false, Ganzzahlen oder endliche Zahlen. Bei Arrays, Objekten, Nullwerten oder Auswertungsfehlern schlägt die Ermittlung der Zuordnung fehl. OpenAI wandelt skalare Ergebnisse in Zeichenfolgen um, bevor es sie mit den Werten der Zuordnung vergleicht. So wird beispielsweise true zu "true" und 7 zu "7".
Für Zuordnungsschlüssel mit dem Präfix openai. berücksichtigt OpenAI ausschließlich Werte aus Attributtransformationen. Unveränderte Claims im Subject-Token, die bereits mit openai. beginnen, haben nur dann Einfluss auf die Zuordnung, wenn du eine passende Transformation konfigurierst.
JWKS verwalten und Schlüssel rotieren
OpenAI überprüft OIDC-Subject-Tokens anhand der Schlüsselquelle, die beim Identitätsanbieter für Workloads konfiguriert ist:
- OIDC-Discovery: OpenAI ruft beim Aussteller
/.well-known/openid-configurationund anschließend die dort angegebenejwks_uriab. OpenAI speichert Discovery-Dokumente und die vom Host abgerufenen JWKS-Daten 600 Sekunden lang im Cache. - Benutzerdefinierte OIDC-Discovery: OpenAI ruft
/.well-known/openid-configurationunter der konfigurierten benutzerdefinierten Discovery-Basis-URL ab und anschließend die dort angegebenejwks_uri. Deriss-Claim des Tokens muss weiterhin mit der URL des OIDC-Ausstellers übereinstimmen. - Schlüssel bei fehlendem Treffer aktualisieren: Findet OpenAI die
kiddes Tokens nicht im zwischengespeicherten JWKS, aktualisiert OpenAI das JWKS und sucht erneut, bevor es das Token ablehnt. - Hochgeladenes JWKS: Ist Hochgeladenes JWKS zur Tokenprüfung verwenden aktiviert, verwendet OpenAI das beim Anbieter gespeicherte JWKS. OpenAI führt dann keine OIDC-Discovery durch und ruft kein JWKS von einem entfernten Host ab. Sobald die aktualisierte Anbieterkonfiguration für den Tokenaustausch verfügbar ist, verwenden neue Austauschvorgänge das gespeicherte JWKS.
- Schlüsselsätze: Ein JWKS kann mehrere öffentliche Schlüssel enthalten. Jeder Schlüssel muss eine eindeutige, nicht leere
kidhaben.
Veröffentliche beim Wechsel der Signaturschlüssel für die Dauer der Übergangsphase sowohl die alten als auch die neuen öffentlichen Schlüssel im JWKS des Ausstellers. So akzeptiert OpenAI sowohl weiterhin gültige Tokens mit der alten Signatur als auch Tokens, die mit dem neuen Schlüssel signiert wurden. Wenn du ein hochgeladenes JWKS verwendest, aktualisiere die Anbieterkonfiguration, bevor du Tokens mit der neuen kid ausstellst. OpenAI lehnt Tokens ab, deren Signaturschlüssel im konfigurierten JWKS fehlt.
Dienstkontozuordnung konfigurieren
Eine Dienstkontozuordnung legt fest, welche externen Identitäten sich Zugriffstokens für ein OpenAI-Dienstkonto ausstellen lassen können.
Bei X.509-Anbietern verwenden Zuordnungsschlüssel abgeleitete openai.*-Attribute. Verwende möglichst eine exakte Zuordnung über openai.subject. Unveränderte JWT-Claims wie sub, aud und iss gelten nur für OIDC-Anbieter.
Die Konfiguration umfasst folgende Optionen:
| Option | Beschreibung |
|---|---|
| Name | Ein innerhalb des Identitätsanbieters für Workloads eindeutiger Name für die Zuordnung. |
| Schlüssel | Der Attributschlüssel für den Vergleich. Verwende einen unveränderten Token-Claim wie sub, aud oder iss oder ein abgeleitetes Attribut wie openai.subject. |
| Wert | Der Attributwert, der übereinstimmen muss, damit OpenAI ein Token ausstellt. |
| Beschreibung | Optionale Beschreibung der Zuordnung. |
| Projekt | Das Projekt, zu dem das Zieldienstkonto gehört. |
| Dienstkonto | Das Dienstkonto, das der Workload verwenden darf. Du kannst im ausgewählten Projekt ein neues Dienstkonto erstellen oder ein vorhandenes auswählen. |
| Berechtigungen | Optionale API-Berechtigungen, die den Zugriff der über diese Zuordnung ausgestellten Tokens weiter einschränken. Sie können keine Rechte gewähren, die über die des zugeordneten Dienstkontos hinausgehen. |
Attributwerte müssen skalare JSON-Werte sein. Zeichenfolgen dürfen mit einem einzelnen Platzhalter enden, wenn davor ein nicht leeres Präfix steht, etwa repo:example/*. Ein Platzhalter allein oder in der Mitte eines Werts wird nicht unterstützt.
Gültige Werte mit Platzhalter:
repo:openai/*repository:my-org/*
Nicht unterstützte Werte mit Platzhalter:
*repo:*:prodrepo/*/main
Das Dashboard zeigt die Einschränkungen der Zuordnung als Berechtigungen an. Die Antwort auf eine Tokenaustauschanfrage enthält dieselben Einschränkungen als OAuth-Scopes in der Eigenschaft scope. Zuordnungen dürfen keine Scopes der Admin API enthalten. Für nachfolgende API-Aufrufe gelten weiterhin die üblichen Autorisierungsprüfungen.
Beispiel zur Ermittlung der Zuordnung
Nachdem OpenAI die externe Identität überprüft hat, ermittelt es die passende Zuordnung. OpenAI sucht nach Zuordnungen für die in der Anfrage angegebenen IDs identity_provider_id und service_account_id. Dabei überspringt es deaktivierte Zuordnungen und wertet für jede Zuordnung nur die benötigten Attribute aus. OpenAI stellt nur dann ein Token aus, wenn bei genau einer aktivierten Zuordnung alle konfigurierten Attribute übereinstimmen.
Angenommen, ein Token von GitHub Actions enthält folgende Claims:
{
"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"
}
Der Anbieter kann daraus ein Attribut ableiten:
[
{
"attribute": "openai.repository_ref",
"expression": "assertion.repository + \"@\" + assertion.ref"
}
]
Die Dienstkontozuordnung kann dann sowohl unveränderte als auch abgeleitete Attribute voraussetzen:
| Schlüssel | Wert |
|---|---|
iss |
https://token.actions.githubusercontent.com |
sub |
repo:my-org/my-repo:* |
openai.repository_ref |
my-org/my-repo@refs/heads/main |
Alle drei Werte müssen übereinstimmen. Der Wert für sub endet mit einem Platzhalter und passt daher zu jedem Wert mit dem Präfix repo:my-org/my-repo:. Den Wert für den Schlüssel openai.repository_ref liefert die Attributtransformation. Ein gleichnamiger unveränderter Token-Claim zählt dafür nicht.
Wenn mehrere aktivierte Zuordnungen zu einer Austauschanfrage passen, lehnt OpenAI die Anfrage ab. OpenAI verlangt eine eindeutige Zuordnung für jedes Paar (provider, service account) und führt die Berechtigungen verschiedener Zuordnungen nicht zusammen.
Workload verbinden
Verwende das SDK-Beispiel in der Anleitung für deinen Identitätsanbieter oder rufe den Endpunkt für den Tokenaustausch direkt auf. Informationen zu Anfrage- und Antwortfeldern, zur Autorisierung und zu aktuellen Einschränkungen findest du in der Referenz zum Tokenaustausch für Workload-Identitäten.
Zugriffstoken erneuern
Wenn du den Tokenaustausch selbst verwaltest, übergib access_token und expires_at gemeinsam vom Tokendienst an die Anwendung. Das Feld expires_at gibt den absoluten Ablaufzeitpunkt in UTC als Unix-Zeitstempel in Sekunden an. Plane die Erneuerung vor diesem Zeitpunkt ein und berücksichtige dabei Zeitabweichungen zwischen Systemen und die Latenz der Anfrage.
Das Feld expires_in gibt die Gültigkeitsdauer des Tokens ab der Ausstellung in Sekunden an. Ein um 12:00 Uhr UTC ausgestelltes Token mit expires_in: 3600 läuft beispielsweise um 13:00 Uhr UTC ab, auch wenn ein anderer Dienst es erst um 12:05 Uhr UTC erhält. Übertragung und Verarbeitung verlängern die Gültigkeitsdauer nicht. Details findest du in der Beschreibung der Antwortfelder.
Beim Tokenaustausch erhältst du kein Refresh-Token. Wiederhole den Austausch mit einem gültigen externen Identitätstoken oder Clientzertifikat, um das Zugriffstoken zu erneuern.
Workload-Identität mit Codex verwenden
Verwende diese Variante für vertrauenswürdige Codex-Automatisierungen in einem verwalteten ChatGPT-Workspace. Anstelle eines Dienstkontos der API-Plattform ordnet Codex dem Workload ein ChatGPT-Benutzerkonto oder ein Dienstkonto im Workspace zu.
Die Identitätsföderation für Codex-Workloads befindet sich in der Betaphase und muss für deinen Workspace aktiviert werden. Um Zugriff zu beantragen, wende dich an deine Ansprechperson bei OpenAI oder an den OpenAI-Support.
Die Referenz zu Föderationsregeln erklärt, wie eine einzelne Regel mehrere externe Subjekte akzeptieren und sie demselben ChatGPT-Prinzipal zuordnen kann.
Verbindungsprobleme beheben
OpenAI lehnt das Identitätstoken ab
Dekodiere das Token lokal. Vergleiche die Claims iss, aud, sub, exp und iat sowie die anbieterspezifischen Claims mit der Konfiguration des Anbieters. Füge keine Tokens aus Produktivumgebungen in JWT-Tools von Drittanbietern ein.
Vergleiche bei der OpenAI API die Tokenattribute auch mit der ausgewählten Dienstkontozuordnung. Vergleiche sie bei Codex mit der ausgewählten Föderationsregel.
Die Zuordnung für die OpenAI API passt nicht
Prüfe, ob die Anfrage die IDs des vorgesehenen Identitätsanbieters und des vorgesehenen Dienstkontos verwendet, ob die Zuordnung aktiv ist und ob genau eine Zuordnung passt. Die Fehlerreferenz zum Tokenaustausch beschreibt die einzelnen Fehlerkategorien.
Codex meldet eine unvollständige Konfiguration
Prüfe, ob dem Codex-Prozess beide erforderlichen Umgebungsvariablen für die Workload-Identität zur Verfügung stehen und ob OPENAI_IDENTITY_TOKEN_FILE einen absoluten Pfad zu einer Datei mit einem aktuellen Token enthält. Prüfe die Berechtigungen der Datei und des übergeordneten Verzeichnisses.
Codex verwendet andere Zugangsdaten
Lade beide erforderlichen Umgebungsvariablen für die Workload-Identität in den Codex-Prozess. Sobald eine der beiden Variablen vorhanden ist, verwendet Codex vorrangig die Identitätsföderation (WIF). API-Schlüssel, Zugriffstokens und gespeicherte Anmeldedaten haben eine niedrigere Priorität. Starte einen neuen Prozess mit der heruntergeladenen Konfiguration und führe dann erneut codex login status aus.
Sicherheitsempfehlungen
- Verwende für jede Anwendung oder jeden Workload einen eigenen Prinzipal.
- Trenne Produktivumgebungen von anderen Umgebungen.
- Prüfe Claim-Werte möglichst auf exakte Übereinstimmung und vermeide weit gefasste Muster.
- Gewähre dem Workload nur die Zugriffsrechte, die er benötigt.
- Wähle kurze Gültigkeitsdauern für Zugriffstokens.
- Überprüfe Anbieter, Zuordnungen und Regeln und entferne diejenigen, die nicht mehr verwendet werden.
- Prüfe Fehler beim Tokenaustausch und unerwartete Zugriffsmuster.