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

Identitätsföderation für Workloads

Authentifiziere Workloads für die OpenAI API und Codex, ohne langlebige Zugangsdaten zu speichern.

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.

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:

  1. Der Identitätsanbieter legt fest, welchem externen Aussteller OpenAI vertraut und wie OpenAI dessen signierte Tokens oder Zertifikatsidentitäten überprüft.
  2. 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.
  3. 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:

  1. 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.
  2. Der Workload übermittelt seine externe Identität zusammen mit den IDs, die das jeweilige Produkt benötigt.
  3. OpenAI überprüft das Token oder Zertifikat und wertet anschließend die konfigurierte Zuordnung oder Regel aus.
  4. 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:

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-configuration und anschließend die dort angegebene jwks_uri ab. OpenAI speichert Discovery-Dokumente und die vom Host abgerufenen JWKS-Daten 600 Sekunden lang im Cache.
  • Benutzerdefinierte OIDC-Discovery: OpenAI ruft /.well-known/openid-configuration unter der konfigurierten benutzerdefinierten Discovery-Basis-URL ab und anschließend die dort angegebene jwks_uri. Der iss-Claim des Tokens muss weiterhin mit der URL des OIDC-Ausstellers übereinstimmen.
  • Schlüssel bei fehlendem Treffer aktualisieren: Findet OpenAI die kid des 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 kid haben.

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:*:prod
  • repo/*/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.

Weiterführende Dokumentation