Mit Mutual TLS (mTLS) prüft OpenAI bei API-Anfragen zusätzlich das TLS-Clientzertifikat. Sobald du für eine Organisation oder ein Projekt ein vertrauenswürdiges Zertifikat aktivierst, muss der Client bei Anfragen in diesem Geltungsbereich zusätzlich zu den üblichen Bearer-Zugangsdaten ein akzeptiertes Clientzertifikat vorlegen.
Verwende mTLS, wenn ein Workload seinen privaten Clientschlüssel sicher speichern kann und OpenAI die Identität des Workloads anhand seines Zertifikats prüfen soll, bevor OpenAI eine API-Anfrage autorisiert. mTLS ersetzt weder API-Schlüssel noch Zugangsdaten für Dienstkonten oder Zugriffstoken für Workload-Identitäten.
Die Föderation von Workload-Identitäten mit X.509 verwendet dieselben aktiven mTLS-Vertrauensanker. Beim Austausch des Zertifikats erhältst du ein kurzlebiges Bearer-Token. Bei nachfolgenden API-Aufrufen musst du dieses Token zusammen mit einem akzeptierten mTLS-Zertifikat für die API senden. Weitere Informationen findest du in der Anleitung Föderation von Workload-Identitäten mit X.509-Zertifikaten konfigurieren.
Vor der mTLS-Konfiguration
Jede API-Organisation kann mTLS über die reguläre rollenbasierte Zugriffskontrolle (RBAC) verwalten:
- Mit
api.mtls.readkann eine Identität Zertifikatseinstellungen auflisten, einsehen und testen. - Mit
api.mtls.writekann eine Identität Zertifikate hochladen, aktualisieren, aktivieren, deaktivieren und löschen.
Die Rolle für die Organisationsinhaberschaft umfasst diese Berechtigungen. Du kannst sie auch über eine benutzerdefinierte Rolle vergeben. Weitere Informationen findest du in der Anleitung Berechtigungen auf der OpenAI-Plattform verwalten.
Für die Konfiguration brauchst du:
- Für jeden Workload ein Clientzertifikat und den zugehörigen privaten Schlüssel.
- Alle Zwischenzertifikate, die für einen Zertifikatspfad vom Clientzertifikat zu deinem Vertrauensanker erforderlich sind.
- Einen stabilen, PEM-kodierten Vertrauensanker, den du auf Organisations- oder Projektebene aktivieren kannst.
- Ein unkritisches Projekt und ein erprobtes Wiederherstellungsverfahren, bevor du mTLS für den Datenverkehr im Produktivbetrieb aktivierst.
Bewahre private Schlüssel außerhalb der Versionsverwaltung auf. Schreibe keine privaten Schlüssel, Zertifikatsinhalte oder Bearer-Zugangsdaten in Protokolle.
Vertrauensanker hochladen und aktivieren
Beim Hochladen wird das Zertifikat gespeichert. Erst mit der Aktivierung wird mTLS für Anfragen verbindlich.
- Öffne Organisationseinstellungen > Sicherheit > Mutual TLS.
- Lade für jedes Zertifikatsobjekt einen PEM-kodierten Vertrauensanker hoch. Wähle einen Namen, an dem du die Zertifizierungsstelle und die jeweilige Generation bei der Rotation erkennst.
- Optional kannst du mit einem CEL-Filter einschränken, welche verifizierten Clientzertifikate der Vertrauensanker akzeptiert.
- Aktiviere das Zertifikat zunächst für ein unkritisches Projekt. Sende von jedem vorgesehenen Workload repräsentative Anfragen über einen mTLS-Host für die API.
- Aktiviere das Zertifikat nach erfolgreicher Prüfung für weitere Projekte oder für die Organisation.
Du kannst Zertifikate auch über die API verwalten:
| Aufgabe | Endpunkt |
|---|---|
| Zertifikat hochladen | POST /v1/organization/certificates |
| Zertifikate der Organisation auflisten | GET /v1/organization/certificates |
| Zertifikat abrufen, aktualisieren oder löschen | GET, POST oder DELETE /v1/organization/certificates/{certificate_id} |
| Zertifikate für eine Organisation aktivieren oder deaktivieren | POST /v1/organization/certificates/activate oder POST /v1/organization/certificates/deactivate |
| Zertifikate für ein Projekt auflisten, aktivieren oder deaktivieren | GET /v1/organization/projects/{project_id}/certificates, POST /v1/organization/projects/{project_id}/certificates/activate oder POST /v1/organization/projects/{project_id}/certificates/deactivate |
Verwende Zugangsdaten mit der jeweils erforderlichen Berechtigung api.mtls.read oder api.mtls.write. Die Schemas für Anfragen und Antworten findest du in der API-Referenz für Organisationszertifikate.
Anforderungen an Zertifikate
Verwende pro Zertifikatsobjekt einen PEM-kodierten Vertrauensanker. Das Zertifikat muss beim Hochladen gültig sein und darf erst mehr als einen Tag nach dem Hochladen ablaufen. Für die Prüfung der Anfrage muss das Clientzertifikat einen Authority Key Identifier (AKI) enthalten.
Damit eine Anfrage die mTLS-Prüfung besteht, müssen folgende Voraussetzungen erfüllt sein:
- Das Clientzertifikat muss zum Zeitpunkt der Anfrage gültig und für die TLS-Clientauthentifizierung geeignet sein.
- Vom Clientzertifikat muss ein gültiger Zertifikatspfad zu einem aktiven Vertrauensanker auf Organisations- oder Projektebene führen.
- Enthält der Pfad Zwischenzertifikate, muss der Client sie beim TLS-Handshake vorlegen.
- Der konfigurierte Vertrauensanker und die Zertifikatskette des Clients müssen die standardmäßige X.509-Pfadprüfung für Clientzertifikate bestehen.
Enthält ein Upload mehrere PEM-kodierte Zertifikate, verwendet OpenAI bei der Prüfung der mitgesendeten Kette nur das erste konfigurierte Zertifikat als Vertrauensanker. Verlass dich daher nicht darauf, dass OpenAI den Upload als PEM-Bündel verarbeitet.
OpenAI ruft fehlende Zwischenzertifikate nicht über URLs aus der Erweiterung Authority Information Access (AIA) ab. OpenAI prüft auch keine Zertifikatssperrlisten (CRL) und führt keine Prüfungen über das Online Certificate Status Protocol (OCSP) durch. Lege die vollständige erforderliche Kette vor. Reagiere auf Sicherheitsvorfälle, indem du Zertifikate rotierst oder deaktivierst und deine eigenen Verfahren zur Verwaltung des Zertifikatslebenszyklus anwendest.
Reihenfolge der Zertifikatsprüfung
OpenAI prüft aktive Zertifikate auf Projektebene vor aktiven Zertifikaten auf Organisationsebene. Gibt es auf keiner der beiden Ebenen ein aktives Zertifikat, erfolgt für die Anfrage keine zusätzliche Zertifikatsprüfung durch mTLS.
Wenn ein aktives Zertifikat vorhanden ist, prüft OpenAI die Identität des Clients in dieser Reihenfolge:
- OpenAI versucht zunächst die bestehende direkte Prüfung. Dabei prüft OpenAI das Clientzertifikat direkt anhand eines aktiven Vertrauensankers, ohne Zwischenzertifikate aus der Anfrage heranzuziehen.
- Findet die direkte Prüfung keine Übereinstimmung und tritt dabei kein Fehler auf, prüft OpenAI die mitgesendete Kette. Dazu verwendet OpenAI das Clientzertifikat und die über die TLS-Verbindung vorgelegten Zwischenzertifikate.
- Ist der Zertifikatspfad gültig und ist für das aktive Zertifikat ein CEL-Filter konfiguriert, wendet OpenAI diesen Filter auf das verifizierte Clientzertifikat an.
Die Prüfung der mitgesendeten Zertifikatskette ist standardmäßig verfügbar.
OpenAI greift auf die mitgesendete Kette zurück, wenn die direkte Prüfung regulär ohne Übereinstimmung endet. Bei Fehlern während der direkten Prüfung ist das nicht immer möglich. Die Anfrage kann ohne Prüfung der vorgelegten Kette fehlschlagen, wenn Zertifikatsdaten fehlen oder fehlerhaft formatiert sind oder der AKI fehlt. Das gilt auch, wenn bei der direkten Prüfung nach der Auswahl eines Vertrauensankers ein deterministischer Fehler auftritt.
Clientzertifikate mit CEL filtern
Du kannst einem hochgeladenen Zertifikat einen Filter in der Common Expression Language (CEL) hinzufügen. Damit schränkst du ein, welche verifizierten Clientzertifikate dieser Vertrauensanker akzeptiert. Der Ausdruck muss einen booleschen Wert ergeben. OpenAI wertet ihn sowohl bei der direkten Prüfung als auch bei der Prüfung der mitgesendeten Kette anhand des verifizierten Clientzertifikats aus.
In CEL stehen folgende Felder zur Verfügung:
subject.common_name,subject.country_code,subject.organization,subject.organizational_unit,subject.locality,subject.province,subject.street_addressundsubject.postal_code.subject_alt_namesist eine Liste, deren Einträge die Feldertype,valueundoidenthalten. Unterstützte SAN-Typen sindDNS,EMAIL,IP_ADDRESS,URIundCUSTOM.
So kannst du beispielsweise verlangen, dass das Zertifikat die Organisationseinheit für den Produktivbetrieb und einen alternativen DNS-Namen (DNS-SAN) in einem bestimmten Namensraum enthält:
subject.organizational_unit == "Production" &&
subject_alt_names.exists(san, san.type == DNS && san.value.endsWith(".example.com"))
Besteht das Zertifikat die Pfadprüfung, erfüllt aber die Filterbedingung nicht, schlägt die Anfrage mit certificate_attribute_verification_failed fehl. OpenAI lehnt eine Richtlinie beim Speichern ab, wenn sie die Validierung nicht besteht.
Einen mTLS-Host verwenden
Sende API-Anfragen an einen mTLS-Host statt an api.openai.com:
| Host | Verwendung |
|---|---|
mtls.api.openai.com |
Standardhost für API-Anfragen mit mTLS. |
mtls-us.api.openai.com |
Regionaler Host für API-Anfragen mit mTLS in den USA. |
mtls-eu.api.openai.com |
Regionaler Host für API-Anfragen mit mTLS in der EU. |
mTLS ist an den Host gebunden. Verwende dieselbe /v1-Route, die du auf der entsprechenden API-Schnittstelle aufrufen würdest. Teste alle APIs und Modelle, die dein Workload nutzt. Je nach regionalem Host können unterschiedliche Routen und Modelle verfügbar sein.
So sendest du beispielsweise die üblichen Bearer-Zugangsdaten und ein Clientzertifikat an den standardmäßigen mTLS-Host:
export 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"
In der Datei mit der Zertifikatskette sollte zuerst das Clientzertifikat stehen, gefolgt von allen erforderlichen Zwischenzertifikaten. Sende keine Zertifikatsdaten in HTTP-Headern oder im Anfragetext.
Für den Zertifikatsaustausch bei der Föderation von Workload-Identitäten mit X.509 ist ein eigener Endpunkt fest vorgegeben: POST https://mtls.auth.openai.com/oauth/token. Bei diesem Austausch erhältst du ein kurzlebiges Bearer-Token. Eine API-Authentifizierung allein per Zertifikat ist damit nicht möglich. Den vollständigen Aufbau der Anfrage findest du in der Referenz zum Tokenaustausch für Workload-Identitäten.
Zertifikate rotieren
Lass den alten und den neuen Vertrauensanker bei der Rotation vorübergehend parallel aktiv, damit bestehende Workloads weiter funktionieren:
- Lade den neuen Vertrauensanker hoch, ohne den alten zu deaktivieren.
- Aktiviere den neuen Vertrauensanker in jedem vorgesehenen Projekt oder auf Organisationsebene.
- Aktualisiere die Workloads so, dass sie Clientzertifikate vorlegen, deren Zertifikatskette zum neuen Vertrauensanker führt. Teste anschließend alle mTLS-Hosts und API-Schnittstellen, die diese Workloads nutzen.
- Deaktiviere den alten Vertrauensanker, sobald alle Workloads umgestellt sind.
- Lösche das alte Zertifikat erst, wenn du es für die Organisation und für 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
Anhand der stabilen Fehlercodes kannst du Konfigurationsfehler von vorübergehenden Dienstfehlern unterscheiden:
| Fehlercode | Was du prüfen solltest |
|---|---|
certificate_required |
Für die Anfrage gilt ein aktives Zertifikat, aber der Client hat die erforderlichen Clientzertifikatsdaten nicht vorgelegt. |
invalid_certificate |
OpenAI kann das Clientzertifikat nicht dekodieren oder einlesen, oder dem Zertifikat fehlt der für die Prüfung erforderliche AKI. |
certificate_verification_failed |
Weder direkt vom Clientzertifikat noch über die vorgelegte Kette führt ein gültiger Pfad zu einem aktiven Vertrauensanker. |
certificate_attribute_verification_failed |
Der Zertifikatspfad ist gültig, aber der CEL-Filter hat das verifizierte Clientzertifikat abgelehnt. |
authentication_temporarily_unavailable |
Eine Zeitüberschreitung bei der Prüfung, ein Fehler in einer internen Abhängigkeit oder ein Fehler bei der CEL-Auswertung hat zum HTTP-Statuscode 503 geführt. Wiederhole die Anfrage nach deinem üblichen Verfahren für vorübergehende Fehler. |
Bei Verwaltungsanfragen bedeutet mtls_certificate_invalid, dass die hochgeladenen PEM-Daten die Validierung nicht bestanden haben. Bei expired_certificate läuft das Zertifikat zu früh ab oder ist bereits abgelaufen. Bei mtls_cel_policy_invalid besteht der Filter die Validierung nicht. Bei certificate_in_use musst du das Zertifikat deaktivieren, bevor du es löschen kannst.
Aktuelle Einschränkungen
- Eine Organisation kann bis zu 50 Zertifikatsobjekte hochladen.
- mTLS ergänzt die reguläre API-Authentifizierung um eine Zertifikatsprüfung. Ein Zertifikat allein reicht für die Autorisierung einer API-Anfrage nicht aus.
- OpenAI ruft keine Zwischenzertifikate über AIA ab und führt keine CRL- oder OCSP-Prüfungen durch.
- Private Link ist mit mTLS nicht kompatibel. Wenn du stattdessen eine private Netzwerkverbindung über Azure benötigst, lies die Anleitung zu Private Link.
- Die unterstützten mTLS-Hosts für die API sind
mtls.api.openai.com,mtls-us.api.openai.comundmtls-eu.api.openai.com. Geh nicht davon aus, dass es für jeden anderen regionalen API-Host einen entsprechenden mTLS-Host gibt. - 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 zertifikatsgebundenes Bearer-Token. Weitere Informationen findest du in der Anleitung Föderation von Workload-Identitäten mit X.509-Zertifikaten konfigurieren.