Mutual TLS

Mutual TLS (mTLS) ergänzt Anfragen an die OpenAI API um eine TLS-Clientzertifikatsprüfung. Sobald du ein vertrauenswürdiges Zertifikat für eine Organisation oder ein Projekt aktivierst, müssen Anfragen in diesem Geltungsbereich zusätzlich zu ihren üblichen Bearer-Anmeldedaten ein akzeptiertes Clientzertifikat vorlegen.

Verwende mTLS, wenn ein Workload einen privaten Clientschlüssel sicher verwahren kann und OpenAI seine Zertifikatsidentität prüfen soll, bevor eine API-Anfrage autorisiert wird. mTLS ersetzt weder API-Schlüssel noch Anmeldedaten für Dienstkonten oder Zugriffstoken für Workload-Identitäten.

Bevor du mTLS konfigurierst

Jede API-Organisation kann mTLS über die übliche rollenbasierte Zugriffskontrolle (RBAC) verwalten:

• Mit api.mtls.read kann ein Prinzipal Zertifikatseinstellungen auflisten, anzeigen und testen.
• Mit api.mtls.write kann ein Prinzipal Zertifikate hochladen, aktualisieren, aktivieren, deaktivieren und löschen.

Die Rolle für Organisationsinhaber umfasst diese Berechtigungen. Du kannst sie aber auch über eine benutzerdefinierte Rolle erteilen. Weitere Informationen findest du unter Berechtigungen auf der OpenAI-Plattform verwalten.

Bereite Folgendes vor:

• Ein Clientzertifikat und den zugehörigen privaten Schlüssel für jeden Workload.
• Alle Zwischenzertifikate, die erforderlich sind, um einen Zertifikatspfad vom Clientzertifikat zu deinem Vertrauensanker zu bilden.
• Einen stabilen PEM-kodierten Vertrauensanker, den du auf Organisations- oder Projektebene aktivieren kannst.
• Ein nicht kritisches Projekt und ein getestetes Wiederherstellungsverfahren, bevor du mTLS für Datenverkehr im Produktivbetrieb aktivierst.

Bewahre private Schlüssel außerhalb der Versionsverwaltung auf. Protokolliere keine privaten Schlüssel, Zertifikatsinhalte oder Bearer-Anmeldedaten.

Vertrauensanker hochladen und aktivieren

Beim Hochladen wird ein Zertifikat gespeichert, mTLS jedoch noch nicht erzwungen. Erst die Aktivierung ändert, wie Anfragen behandelt werden.

1. Öffne Organisationseinstellungen > Sicherheit > Mutual TLS.
2. Lade für jedes Zertifikatsobjekt einen PEM-kodierten Vertrauensanker hoch. Gib ihm einen Namen, der die Zertifizierungsstelle und die Rotationsgeneration erkennen lässt.
3. Füge optional einen CEL-Filter hinzu, der einschränkt, welche verifizierten Clientzertifikate dieser Vertrauensanker akzeptieren kann.
4. Aktiviere das Zertifikat zunächst für ein nicht kritisches Projekt. Sende repräsentative Anfragen über einen mTLS-API-Host von jedem vorgesehenen Workload aus.
5. Aktiviere das Zertifikat nach erfolgreicher Validierung für weitere Projekte oder für die Organisation.

Du kannst Zertifikate auch über die API verwalten:

Verwende Anmeldedaten mit der erforderlichen Berechtigung api.mtls.read oder api.mtls.write. Die Anfrage- und Antwortschemas findest du in der API-Referenz für Organisationszertifikate.

Zertifikatsanforderungen

Verwende einen PEM-kodierten Vertrauensanker pro Zertifikatsobjekt. Der Upload muss ein gültiges Zertifikat enthalten, das frühestens mehr als einen Tag nach dem Hochladen abläuft. Für die Anfrageprüfung muss das Clientzertifikat einen Authority Key Identifier (AKI) enthalten.

Damit eine Anfrage die mTLS-Prüfung besteht, gelten folgende Anforderungen:

• Das Clientzertifikat muss zum Zeitpunkt der Anfrage gültig und für die TLS-Clientauthentifizierung geeignet sein.
• Vom Clientzertifikat muss sich ein gültiger Zertifikatspfad zu einem aktiven Vertrauensanker auf Organisations- oder Projektebene bilden lassen.
• Wenn der Zertifikatspfad Zwischenzertifikate enthält, muss der Client diese beim TLS-Handshake vorlegen.
• Der konfigurierte Vertrauensanker und die Zertifikatskette des Clients müssen die standardmäßige X.509-Pfadvalidierung für Clientzertifikate bestehen.

Enthält ein Upload mehr als ein PEM-kodiertes Zertifikat, verwendet die Prüfung der mit der Anfrage übermittelten Zertifikatskette nur das erste konfigurierte Zertifikat als Vertrauensanker. Verlasse dich nicht auf die Semantik von PEM-Bündeln.

OpenAI ruft keine fehlenden Zwischenzertifikate von Authority Information Access (AIA)-URLs ab und führt weder Prüfungen anhand von Zertifikatssperrlisten (CRL) noch über das Online Certificate Status Protocol (OCSP) durch. Übermittle die vollständige erforderliche Zertifikatskette. Reagiere auf Sicherheitsvorfälle durch Zertifikatsrotation, Deaktivierung und eigene Kontrollen für den Zertifikatslebenszyklus.

Prüfreihenfolge verstehen

OpenAI prüft aktive Zertifikate auf Projektebene vor aktiven Zertifikaten auf Organisationsebene. Wenn auf keiner der beiden Ebenen ein aktives Zertifikat vorhanden ist, fügt mTLS der Anfrage keine Zertifikatsprüfung hinzu.

Wenn ein aktives Zertifikat vorhanden ist, prüft OpenAI die Clientidentität in dieser Reihenfolge:

1. OpenAI versucht zunächst den bestehenden direkten Prüfpfad. Dabei wird das Clientzertifikat direkt gegen einen aktiven Vertrauensanker geprüft, ohne die mit der Anfrage übermittelten Zwischenzertifikate zu verwenden.
2. Findet sich beim direkten Prüfpfad regulär keine Übereinstimmung, versucht OpenAI, die übermittelte Zertifikatskette zu prüfen. Dazu werden das Clientzertifikat und die über die TLS-Verbindung vorgelegten Zwischenzertifikate verwendet.
3. Wird ein Zertifikatspfad erfolgreich verifiziert, wertet OpenAI den CEL-Filter des aktiven Zertifikats, sofern vorhanden, anhand des verifizierten Clientzertifikats aus.

Die Prüfung der mit der Anfrage übermittelten Zertifikatskette ist standardmäßig verfügbar.

Die Prüfung der übermittelten Zertifikatskette dient als Fallback, wenn regulär keine Übereinstimmung gefunden wird. Sie fängt nicht jeden Fehler des direkten Prüfpfads ab. Fehlende oder fehlerhafte Zertifikatsdaten, ein fehlender AKI oder ein deterministischer Fehler nach der Auswahl eines Vertrauensankers im direkten Prüfpfad können dazu führen, dass die Anfrage fehlschlägt, ohne dass die übermittelte Kette geprüft wird.

Clientzertifikate mit CEL filtern

Füge einem hochgeladenen Zertifikat optional einen Filter in Common Expression Language (CEL) hinzu, um einzuschränken, welche verifizierten Clientzertifikate dieser Vertrauensanker akzeptiert. Der Ausdruck muss einen booleschen Wert ergeben. Er wird sowohl beim direkten Prüfpfad als auch bei der Prüfung der übermittelten Zertifikatskette anhand des verifizierten Clientzertifikats ausgewertet.

CEL stellt diese Felder bereit:

• subject.common_name, subject.country_code, subject.organization, subject.organizational_unit, subject.locality, subject.province, subject.street_address und subject.postal_code.
• subject_alt_names, eine Liste, deren Einträge type, value und oid bereitstellen. Unterstützte SAN-Typkennungen sind DNS, EMAIL, IP_ADDRESS, URI und CUSTOM.

Verlange beispielsweise eine Organisationseinheit für den Produktivbetrieb und einen DNS-SAN in einem bestimmten Namensraum:

subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))

Ein Zertifikat, das erfolgreich verifiziert wird, aber den Filter nicht erfüllt, wird mit dem Fehler certificate_attribute_verification_failed abgelehnt. OpenAI lehnt eine Richtlinie beim Speichern ab, wenn sie die Validierung nicht besteht.

Einen mTLS-Host verwenden

Sende API-Datenverkehr an einen mTLS-Host statt an api.openai.com:

mTLS ist hostbasiert. Verwende dieselbe /v1-Route, die du auf der entsprechenden API-Schnittstelle aufrufen würdest, und teste jede API und jedes Modell, die dein Workload nutzt. Die Verfügbarkeit von Routen und Modellen kann je nach regionalem Host unterschiedlich sein.

Sende beispielsweise normale Bearer-Zugangsdaten und ein Clientzertifikat an den Standard-mTLS-Host:

1234567export OPENAI_MTLS_CERT_CHAIN="/path/to/client-chain.pem"
export OPENAI_MTLS_KEY="/path/to/client-key.pem"

curl https://mtls.api.openai.com/v1/models \
  --cert "$OPENAI_MTLS_CERT_CHAIN" \
  --key "$OPENAI_MTLS_KEY" \
  --header "Authorization: Bearer $OPENAI_API_KEY"

Die Datei mit der Zertifikatskette sollte zuerst das Clientzertifikat enthalten, gefolgt von allen erforderlichen Zwischenzertifikaten. Sende keine Zertifikatsdaten in HTTP-Headern oder Anfragebodys.

Die Föderation von Workload-Identitäten mit X.509 verwendet einen separaten, exakt festgelegten Austauschendpunkt: POST https://mtls.auth.openai.com/oauth/token. Dieser Austausch liefert ein kurzlebiges Bearer-Token. Er ermöglicht keine API-Authentifizierung allein anhand eines Zertifikats. Die vollständige Anfragestruktur findest du in der Referenz zum Tokenaustausch für Workload-Identitäten.

Zertifikate rotieren

Rotiere Vertrauensanker mit einer Übergangsphase, in der beide aktiv sind, damit bestehende Workloads weiter funktionieren:

1. Lade den neuen Vertrauensanker hoch, ohne den alten zu deaktivieren.
2. Aktiviere den neuen Vertrauensanker in jedem vorgesehenen Projekt oder auf Organisationsebene.
3. Aktualisiere die Workloads so, dass sie Clientzertifikate vorlegen, deren Kette zum neuen Vertrauensanker führt. Teste anschließend jeden mTLS-Host und jede API-Schnittstelle, die sie nutzen.
4. Deaktiviere den alten Vertrauensanker, nachdem alle Workloads umgestellt wurden.
5. Lösche das alte Zertifikat erst, nachdem du es für die Organisation und jedes Projekt deaktiviert hast.

Du kannst Zwischenzertifikate rotieren, ohne den konfigurierten Vertrauensanker zu ändern. Lege bei nachfolgenden Anfragen die neue vollständige Kette vor.

Fehler bei Anfragen beheben

Unterscheide anhand stabiler Fehlercodes zwischen Konfigurationsfehlern und vorübergehenden Dienstfehlern:

Bei Verwaltungsanfragen bedeutet mtls_certificate_invalid, dass die hochgeladenen PEM-Daten die Validierung nicht bestanden haben. expired_certificate bedeutet, dass das Zertifikat zu früh abläuft oder bereits abgelaufen ist. mtls_cel_policy_invalid bedeutet, dass der Filter die Validierung nicht besteht. certificate_in_use bedeutet, dass du das Zertifikat deaktivieren musst, bevor du es löschst.

Aktuelle Einschränkungen

• Eine Organisation kann bis zu 50 Zertifikatsobjekte hochladen.
• mTLS ergänzt die normale API-Authentifizierung um eine Zertifikatsprüfung. Es ermöglicht keine API-Autorisierung allein anhand eines Zertifikats.
• OpenAI ruft keine Zwischenzertifikate über AIA ab und führt keine CRL- oder OCSP-Prüfungen durch.
• Private Link ist nicht mit mTLS kompatibel. Sieh dir Private Link an, wenn du stattdessen einen privaten Netzwerkpfad in Azure benötigst.
• Die unterstützten mTLS-Hosts der API sind mtls.api.openai.com, mtls-us.api.openai.com und mtls-eu.api.openai.com. Gehe nicht davon aus, dass jeder andere regionale API-Host ein mTLS-Gegenstück hat.
• Die Föderation von Workload-Identitäten mit X.509 gibt kein Refresh-Token zurück und verwendet weder DPoP noch einen cnf-Claim oder ein an ein Zertifikat gebundenes Bearer-Token. Siehe Föderation von Workload-Identitäten mit X.509-Zertifikaten konfigurieren.