Workload-Identitätsföderation

Mit der Workload-Identitätsföderation kann vertrauenswürdige Automatisierung Codex verwenden, ohne ein persönliches Zugriffstoken oder andere langlebige OpenAI-Anmeldedaten zu speichern. Ihre Workload legt ein kurzlebiges Identitätstoken eines von Ihnen bereits betriebenen Anbieters vor. OpenAI überprüft dieses Token und gibt ein kurzlebiges Zugriffstoken für einen Benutzer oder ein Dienstkonto in Ihrem verwalteten ChatGPT-Workspace zurück.

Verwenden Sie Workload-Identitäten für unbeaufsichtigte Codex-Prozesse auf Cloud-Plattformen, in Kubernetes, CI-Systemen und anderen Umgebungen, die OIDC-Token oder SPIFFE JWT-SVIDs ausstellen können. Informationen zum gemeinsamen Vertrauensmodell und zum separaten OpenAI API-Ablauf finden Sie in der Übersicht über Workload-Identitäten.

Voraussetzungen

Sie benötigen:

• Die Berechtigung zum Verwalten von Workload-Identitäten im OpenAI Admin Portal.
• Einen verwalteten ChatGPT-Workspace.
• Einen ChatGPT-Benutzer oder ein Dienstkonto, der beziehungsweise das aktives Mitglied dieses Workspace ist, oder die Berechtigung, während der Einrichtung eines zu erstellen.
• Ein OIDC-Token oder SPIFFE JWT-SVID, dessen Aussteller, Zielgruppe und identifizierende Ansprüche Ihnen bekannt sind.
• Eine Laufzeitumgebung, die dieses Token in einer geschützten Datei unter einem absoluten Pfad aktuell halten kann.
• Codex 0.148.0 oder höher.
• Eine wirksame Codex-Authentifizierungsrichtlinie, die die ChatGPT-Authentifizierung und den durch die Föderationsregel ausgewählten Workspace zulässt. Siehe Anmeldemethode oder Workspace erzwingen.

OpenAI erstellt beim Token-Austausch weder einen Prinzipal noch eine Workspace-Mitgliedschaft. Eine administrierende Person wählt den Prinzipal aus oder erstellt ihn, bevor die Workload eine Verbindung herstellt. Das Erstellen eines menschlichen Benutzers belegt einen Workspace-Arbeitsplatz und unterliegt den Mitgliedschaftsregeln dieses Workspace.

Verwenden Sie unter nativem Windows die elevated Windows-Sandbox. Andere Windows-Sandbox-Modi können die Identitätstoken-Datei nicht vor modellgesteuerten Befehlen schützen.

Identitätstoken abrufen

Ihre Workload-Laufzeitumgebung ruft das vorgelagerte Identitätstoken ab und aktualisiert es. Codex ruft weder Cloud-Metadatendienste noch Clientbibliotheken von Identitätsanbietern in Ihrem Namen auf.

Befolgen Sie die Anleitung für Ihren Anbieter, um die Token-Ausstellung zu konfigurieren und ein Beispieltoken zu prüfen:

• Microsoft Azure
• AWS
• Google Cloud
• Oracle Cloud Infrastructure
• GitHub Actions
• Kubernetes
• SPIFFE

Decodieren Sie ein Beispieltoken lokal und notieren Sie dessen iss, aud, sub und alle weiteren Ansprüche, denen Sie vertrauen möchten. Durch das Decodieren wird die Signatur nicht überprüft. Fügen Sie kein Produktionstoken in eine Website ein und schreiben Sie es nicht in Protokolle.

Workload verbinden

Eine administrierende Person erstellt den Anbieter und die Föderationsregel, bevor Codex gestartet wird.

1. Öffnen Sie Workload identity im OpenAI Admin Portal und wählen Sie anschließend Connect workload aus.
2. Verwenden Sie einen für Codex konfigurierten Anbieter erneut oder erstellen Sie einen. Anbietervoreinstellungen tragen gängige Einstellungen für GitHub Actions, Microsoft Entra ID, Google Cloud, AWS, Kubernetes, SPIFFE und benutzerdefinierte OIDC-Anbieter ein.
3. Wählen Sie Codex und den verwalteten Workspace aus, den die Workload verwenden darf.
4. Fügen Sie die engsten Bedingungen hinzu, die die Workload identifizieren. Gleichen Sie ein Subjekt, exakte Ansprüche, eine CEL-Bedingung oder eine Kombination davon ab. Fügen Sie akzeptierte Zielgruppen hinzu, um einzuschränken, welche Token die Regel akzeptiert. Jede konfigurierte Abgleichsbedingung muss erfüllt sein.
5. Ordnen Sie die Regel einem vorhandenen ChatGPT-Benutzer oder Dienstkonto zu oder erstellen Sie während der Einrichtung eines.
6. Prüfen Sie Anbieter, Bedingungen, Workspace, Prinzipal, Geltungsbereiche und Lebensdauer des Zugriffstokens. Wählen Sie Connect workload und anschließend Download config aus.

Die heruntergeladene Datei enthält eine nicht geheime Föderationsregel-ID und den Pfad, unter dem Codex das Identitätstoken liest. Sie enthält keine Anmeldedaten.

Verwenden Sie zur Automatisierung der Einrichtung die Workload-Identitäts-Admin- API. Informationen zum Verhalten von Abgleichsbedingungen und Beispiele finden Sie in der Referenz zu Föderationsregeln.

Codex-Prozess konfigurieren

Der Prozess, der Codex startet, benötigt diese beiden Workload-Identitätsvariablen:

export OPENAI_FEDERATION_RULE_ID="idpm_..."
export OPENAI_IDENTITY_TOKEN_FILE="/var/run/secrets/openai.com/identity-token"

OPENAI_FEDERATION_RULE_ID ist nicht geheim. Die Token-Datei ist es. Verwenden Sie einen absoluten Pfad in einem dedizierten Verzeichnis wie /var/run/secrets/openai.com, das dem Workload-Konto gehört und den Modus 0700 verwendet. Nur vertrauenswürdige Hostprozesse sollten dort schreiben. Halten Sie das Verzeichnis außerhalb von Repositorys und anderen Pfaden, die für Codex-Tools verfügbar sind. Halten Sie Anmeldedaten aus Protokollen, Shell-Verläufen und Build-Artefakten heraus.

Audit-Zuordnung hinzufügen

Wenn Laufzeitinstanzen eine Föderationsregel gemeinsam verwenden, können Sie jede Instanz in Audit-Ereignissen zur Token-Ausstellung identifizieren. Legen Sie die optionale Variable OPENAI_WORKLOAD_IDENTITY_CONTEXT auf ein als Zeichenfolge codiertes JSON-Objekt fest:

export OPENAI_WORKLOAD_IDENTITY_CONTEXT='{
  "instance_id": "runner-42",
  "display_name": "payments-prod",
  "labels": {
    "environment": "production",
    "region": "us-west-2"
  }
}'

Das Objekt erfordert instance_id. Es kann außerdem display_name und bis zu acht Labels enthalten. Das codierte Objekt darf bis zu 1.024 Byte groß sein. instance_id und display_name dürfen bis zu 128 Zeichen umfassen. Label-Schlüssel dürfen bis zu 64 Zeichen und Label-Werte bis zu 256 Zeichen umfassen.

Bezeichner müssen mit einem ASCII-Buchstaben oder einer Zahl beginnen. Werte können anschließend Buchstaben, Zahlen, ., _, :, /, @ und - enthalten. Label-Schlüssel unterstützen Buchstaben, Zahlen, ., _ und -.

OpenAI behandelt diesen Kontext als clientseitig gemeldete Audit-Zuordnung und nicht als verifizierte Workload-Identität. Er wirkt sich nicht auf Authentifizierung, Autorisierung, Regelabgleich, Geltungsbereiche, Ratenlimits, Widerruf, Funktionsfreigaben oder Metriken aus. Nehmen Sie darin keine Anmeldedaten, Geheimnisse, personenbezogenen Daten, Prompts, Modellausgaben oder andere Customer Content auf.

Für einen gültigen Kontext leitet OpenAI eine stabile Zuordnungs-ID ab, deren Geltungsbereich auf Mandant, Anbieter, Föderationsregel und instance_id beschränkt ist. Für die Zuordnung enthält das Zugriffstoken die ID, aber nicht den Kontext. Das Audit-Ereignis einer erfolgreichen Token-Ausstellung enthält die ID und den normalisierten Kontext. Ein Kontext, der ein Limit überschreitet oder gegen dieses Schema verstößt, führt dazu, dass der Austausch mit invalid_grant fehlschlägt.

Codex liest den Kontext beim Start des Prozesses und übergibt weder ihn noch die Regel- ID oder den Pfad der Token-Datei an modellgesteuerte Shells, Hooks oder MCP-Server. Starten Sie Codex nach einer Änderung des Kontexts neu.

Token-Datei schützen und rotieren

Fügen Sie bei verwalteten Bereitstellungen unter Linux, macOS und WSL das gesamte Token-Verzeichnis zu permissions.filesystem.deny_read in den verwalteten Anforderungen hinzu:

[permissions.filesystem]
deny_read = ["/var/run/secrets/openai.com"]

Dadurch wird verhindert, dass modellgesteuerte Befehle das aktive Token oder eine temporäre Ersatzdatei lesen, während der Codex-Hostprozess das Token weiterhin für den Austausch verwenden kann. Verweigern Sie bei Volumes mit projizierten Token den Zugriff auf den gesamten Token-Mount und alle zugrunde liegenden oder aufgelösten Zielpfade außerhalb davon. Dateimodi und das Bereinigen von Umgebungsvariablen allein schützen Anmeldedaten nicht vor einem anderen Prozess, der als derselbe Benutzer ausgeführt wird. Verwenden Sie unter nativem Windows die oben beschriebene elevated-Sandbox.

Bei Token-Quellen, die keine Datei projizieren, lassen Sie einen vertrauenswürdigen Hostprozess jeden Ersatz innerhalb dieses geschützten Verzeichnisses schreiben und an die richtige Stelle umbenennen. Eine atomare Umbenennung verhindert, dass Codex ein unvollständiges Token liest. Passen Sie beispielsweise dieses hosteigene Aktualisierungsskript an den Token-Befehl Ihres Anbieters an. Stellen Sie das Verzeichnis bereit, bevor Sie das Skript ausführen:

set -eu
TOKEN_DIR="/var/run/secrets/openai.com"
TOKEN_FILE="$TOKEN_DIR/identity-token"
umask 077
TOKEN_TEMP="$(mktemp "$TOKEN_DIR/.identity-token.XXXXXX")"
trap 'rm -f -- "$TOKEN_TEMP"' EXIT
trap 'exit 1' HUP INT TERM
your-identity-provider-command > "$TOKEN_TEMP"
test -s "$TOKEN_TEMP"
mv -f -- "$TOKEN_TEMP" "$TOKEN_FILE"

Führen Sie den Aktualisierungsprozess außerhalb jeder Shell und jedes Tools aus, die beziehungsweise das Codex steuern kann. Behalten Sie die Leseverweigerung während der Aktualisierung und Bereinigung bei. Selbst wenn bei einem erzwungenen Abbruch eine temporäre Datei zurückbleibt, muss diese innerhalb des gesperrten Verzeichnisses verbleiben. Legen Sie keine Workload-Identitätseinstellungen in config.toml ab.

Verbindung überprüfen

Laden Sie die heruntergeladene Umgebung und prüfen Sie die ausgewählte Authentifizierungsmethode:

. ./workload-identity-idpm_example.env
codex login status

In PowerShell:

$env:OPENAI_FEDERATION_RULE_ID = "idpm_..."
$env:OPENAI_IDENTITY_TOKEN_FILE = "C:\run\openai\identity-token"
codex login status

Bei einer erfolgreichen Prüfung wird Logged in using workload identity ausgegeben. Dies bestätigt, dass Codex über die konfigurierte Föderationsregel ein Token ausgetauscht hat. Der Befehl gibt den aufgelösten Workspace, Prinzipal oder die Regel nicht aus. Bestätigen Sie diese Werte im Admin Portal, bevor Sie die Workload starten. Meldet Codex eine andere Authentifizierungsmethode, haben die beiden erforderlichen WIF-Variablen den Prozess nicht erreicht.

Wenn der Anbieter Prevent assertion replay verwendet und die Assertion einen jti- Anspruch besitzt, verbraucht diese Prüfung dessen jti. Schreiben Sie vor dem Start eines weiteren Codex-Prozesses eine neu ausgestellte Assertion mit einem neuen jti.

Führen Sie eine kleine Anfrage aus derselben Umgebung aus:

codex exec "Reply with only: workload identity is working"

Codex tauscht das vorgelagerte Token aus und hält das OpenAI-Zugriffstoken im Arbeitsspeicher. Es schreibt keine der beiden Anmeldedaten in auth.json, den Systemschlüsselbund oder config.toml.

Token aktuell halten

Aktualisieren Sie die Identitätstoken-Datei, bevor das vorgelagerte Token abläuft. Codex liest die Datei erneut, wenn ein weiteres OpenAI-Zugriffstoken benötigt wird. Das OpenAI-Token läuft zum früheren Zeitpunkt aus dem Ablauf des vorgelagerten Tokens oder der Lebensdauer der Föderationsregel ab und ist niemals länger als eine Stunde gültig.

Wenn eine administrierende Person den Wiederholungsschutz aktiviert, muss jedes vorgelagerte JWT über ein eindeutiges jti verfügen. Schreiben Sie vor jedem Austausch, einschließlich Aktualisierungen in einem lang laufenden Prozess, eine neu ausgestellte Assertion mit einem neuen jti. Assertions ohne jti erhalten keinen Wiederholungsschutz.

Codex verwendet innerhalb jedes Hostprozesses eine gemeinsame Austausch-Sitzung im Arbeitsspeicher. Gleichzeitige Anfragen in diesem Prozess verwenden ein gültiges OpenAI-Zugriffstoken erneut und führen beim Ablauf gemeinsam eine einzige Aktualisierung durch. Separate Prozesse führen separate Austausche durch und benötigen daher Assertions, deren Verwendung der Anbieter ihnen gestattet.

Rangfolge der Anmeldedaten

Die beiden erforderlichen Workload-Identitätsvariablen haben Vorrang vor allen anderen Quellen für Anmeldedaten:

1. Wenn entweder OPENAI_FEDERATION_RULE_ID oder OPENAI_IDENTITY_TOKEN_FILE vorhanden ist, wählt Codex die Workload-Identität aus.
2. Wenn nur eine der erforderlichen Variablen vorhanden ist, gibt Codex einen Fehler zurück. Es greift nicht auf einen API key, ein Zugriffstoken oder eine gespeicherte Anmeldung zurück.
3. OPENAI_WORKLOAD_IDENTITY_CONTEXT allein wählt keine Workload-Identität aus.
4. Wenn keine der erforderlichen WIF-Variablen vorhanden ist, wendet Codex die normalen Anmeldedatenregeln für die jeweilige Oberfläche an. Bei Oberflächen, die die Authentifizierung per API key zulassen, hat CODEX_API_KEY in codex exec, codex review, dem TypeScript SDK und codex exec-server --remote Vorrang. Andere Oberflächen können CODEX_ACCESS_TOKEN oder eine gespeicherte Anmeldung verwenden.

Eine SDK-Option apiKey wird zu CODEX_API_KEY, WIF hat jedoch weiterhin Vorrang, wenn eine der beiden erforderlichen WIF-Variablen vorhanden ist. Lassen Sie die Option bei der Verwendung von WIF weg, damit die Workload keine ungenutzten langlebigen Anmeldedaten mitführt.

Um eine bestehende Workload ohne Ausfallzeit zu migrieren, konfigurieren Sie WIF, solange ihre aktuellen Anmeldedaten noch verfügbar sind. Starten Sie einen neuen Prozess mit beiden erforderlichen WIF- Variablen; WIF hat auch dann Vorrang, wenn die alten Anmeldedaten noch vorhanden sind. Nachdem die Workload erfolgreich mit WIF ausgeführt wurde, entfernen Sie die alten Anmeldedaten aus ihrer Laufzeitumgebung und dem Secret-Speicher und widerrufen Sie sie anschließend. Vor dem Widerruf können Sie ein Rollback durchführen, indem Sie beide erforderlichen WIF-Variablen entfernen und einen neuen Prozess starten.

Unterstützte Codex-Oberflächen

Konfigurieren Sie die Workload-Identität auf dem Computer, auf dem der Codex-Prozess ausgeführt wird.

Remote-App-Server- und Exec-Server-Clients senden das vorgelagerte Identitätstoken niemals über ihre Protokolle.

Zugriff ändern oder entfernen

Änderungen an Subjekten, Zielgruppen, Ansprüchen, CEL-Bedingungen, Geltungsbereichen oder der Token- Lebensdauer einer Regel gelten für neue Austausche. Ein vor der Änderung ausgestelltes Token kann bis zum Ende seiner Lebensdauer gültig bleiben.

Deaktivieren Sie einen Anbieter oder eine Regel, um den Zugriff sofort zu beenden. Die Deaktivierung blockiert neue Austausche und widerruft OpenAI-Zugriffstoken, die bereits über diese Ressource ausgestellt wurden. Die Archivierung hat dieselbe Auswirkung auf den Zugriff und kann nicht rückgängig gemacht werden. Eine Änderung des Anbieter- Vertrauens widerruft ebenfalls ausgestellte Token, bevor das neue Vertrauen wirksam wird.

Änderungen auditieren

Das Erstellen, Aktualisieren und Archivieren von Anbietern und Föderationsregeln erzeugt Audit- Ereignisse. Verwenden Sie die Anleitung zur Compliance API und zu Audit-Ereignissen, um die von Ihrem Workspace unterstützten Ereignisse zu exportieren. Korrelieren Sie sie mit den Ausstellungsprotokollen Ihres Identitätsanbieters und zeichnen Sie weder vorgelagerte Assertions noch OpenAI-Zugriffstoken in einem der Systeme auf.

Wenn der Prozess OPENAI_WORKLOAD_IDENTITY_CONTEXT bereitstellt, enthalten erfolgreiche Audit-Ereignisse zur Token-Ausstellung außerdem die stabile Zuordnungs-ID und den oben beschriebenen normalisierten Kontext.

Fehlerbehebung

Informationen zur Anbieterüberprüfung, zu Limits und CEL-Details finden Sie in der Referenz zu Föderationsregeln.