OpenAI Mutual TLS stelt organisaties in staat een extra beveiligingslaag te configureren voor hun OpenAI API-verkeer. Na configuratie moeten API-verzoeken worden gedaan naar https://mtls.api.openai.com (of https://mtls-eu.api.openai.com voor klanten met EU-gegevensresidentie) en verkeer wordt alleen geaccepteerd als de juiste API-sleutel en het juiste clientcertificaat worden opgegeven. mTLS is niet van toepassing op het https://platform.openai.com-dashboard. Deze functie is momenteel in bèta.
Hoe stel ik de mTLS-integratie in?
In de navigatiebalk met instellingen zie je een tabblad ‘Mutual TLS’.
Certificaat uploaden
Certificaat activeren
Na het uploaden van je certificaat is de volgende stap om je certificaat te activeren. Zodra een certificaat voor een project is geactiveerd, vereisen alle API-verzoeken naar dat project ook een bijbehorend clientcertificaat. Als voor een project meerdere certificaten zijn geactiveerd, kun je elk bijbehorend clientcertificaat doorgeven. Als een certificaat voor de organisatie is geactiveerd, geldt het voor alle API-verzoeken en wordt het door alle projecten ‘geërfd’.
Vereisten voor CA-certificaten
Je kunt elk X.509 CA-certificaat in PEM-formaat uploaden dat aan de volgende vereisten voldoet:
ondertekent rechtstreeks je clientcertificaten waarmee je verzoeken wilt doen
heeft de extensies Certificate Authority, Subject Key Identifier en Authority Key Identifier (in KeyIdentifier-formaat)
heeft de Key Usage-machtigingen: ‘Certificate Sign, CRL Sign’
verloopt niet binnen 1 dag
de totale certificaatgrootte moet kleiner zijn dan 16 kb.
Vereisten voor clientcertificaten
Clientcertificaten moeten rechtstreeks zijn ondertekend door de certificaten die je vooraf hebt geüpload. Op dit moment ondersteunen we alleen certificaatketens van één niveau. Daarnaast moeten je clientcertificaten aan de volgende vereisten voldoen:
heeft de extensies Subject Key Identifier en Authority Key Identifier (in KeyIdentifier-formaat)
heeft de Key Usage-machtigingen: ‘Digital Signature, Key Encipherment’
heeft de Extended Key Usage-machtiging: ‘TLS Web Client Authentication’
heeft de Subject Alternative Name-extensie
Veelgestelde vragen
Kan ik mTLS via de API configureren?
Ja — zie de API-referentie op https://platform.openai.com/docs/api-reference/ voor meer informatie.
Welke endpoints ondersteunen mTLS?
Tijdens deze bèta wordt mTLS officieel ondersteund in
/v1/chat/completions (met alle ondersteunde extensies, bijv. image, audio, streaming, enz.)/v1/completions/v1/embeddings/v1/audio/transcriptions/v1/audio/speech/v1/files/v1/batches/v1/responses/v1/images/v1/moderations/v1/realtime (via server-side websockets)/v1/fine_tuning/v1/tunnels
Hoe stuur ik clientcertificaten mee met mijn verzoek?
Voor een cURL-verzoek kun je de opties --cert en --key gebruiken (zie de man-pagina hier). In de meeste andere HTTP-clients zijn er ook manieren om clientcertificaten mee te geven. Voorbeelden: requests in Python, fetch in JS. Via onze officiële SDK's ondersteunen we ook het overschrijven van de HTTP-client — zie hier voor een Python-voorbeeld.
Voordat je mTLS afdwingt voor productieverkeer, moet je controleren of de HTTP-client die je gebruikt goed omgaat met verzoeken om clientcertificaten (sommige, zoals WebSockets in bepaalde browsers, doen dat niet). Houd er rekening mee dat onze server geen certificate_authorities-lijst verstrekt in het verzoek om een clientcertificaat.
Wie kan certificaten openen en wijzigen?
Via de dashboard-UI op https://platform.openai.com/settings/organization/mtls kunnen organisatie-eigenaren certificaten openen en wijzigen. Iedereen met een Admin API Key (https://platform.openai.com/settings/organization/admin-keys) kan certificaten ook openen/wijzigen, maar let op — als je Mutual TLS op organisatieniveau activeert, dwing je certificaten ook af voor deze API-verzoeken. Alle mTLS-wijzigingen zijn zichtbaar in auditlogs.
Hoeveel certificaten kan ik hebben?
Elke organisatie kan maximaal 50 certificaten uploaden, die over projecten kunnen worden gedeeld maar niet met andere organisaties. Je kunt een certificaat atomair voor 10 projecten tegelijk activeren/deactiveren. Je kunt ook 10 certificaten tegelijk activeren/deactiveren voor je organisatie of voor 1 specifiek project.
Kan ik certificaten bijwerken of verwijderen?
Je kunt de namen van je certificaten bijwerken, maar niet de inhoud. Je kunt certificaten ook verwijderen als ze momenteel op geen enkel niveau actief zijn.
Hoe werkt intrekking van certificaten?
Op dit moment ondersteunen we geen CRL's of OCSP-stapling. Het aanbevolen alternatief is om in plaats daarvan je API-sleutel te verwijderen of te roteren. Je kunt ook je CA-certificaten vervangen of clientcertificaten gebruiken met kortere geldigheidsperioden.
Kan ik langere certificaatketens gebruiken?
Op dit moment ondersteunen we alleen ketens van één niveau — d.w.z. je CA-certificaat moet je clientcertificaten rechtstreeks ondertekenen. Neem contact op met je Account Director als je nog vragen hebt.
Wat is de aanbevolen configuratie?
Wanneer je deze functie voor het eerst instelt, raden we aan te beginnen met een stagingproject dat geen officieel productieverkeer bedient. Gebruik dit om te controleren of je certificaten correct op je machines zijn ingesteld en of je API-verkeer met succes kunt verzenden. Daarnaast raden we aan om met het beveiligingsteam van je organisatie te overleggen om je behoeften goed te begrijpen.
Extra ondersteuning
Je kunt de mTLS-functie volledig zelf beheren via het dashboard en de API. Als je mTLS eerst in een shadow mode wilt inschakelen, neem dan contact op met je Account Director of open een supportticket door rechtsonder op deze pagina een nieuwe chat te starten.
Bijlage: terminologie
CA-certificaat: Een van je vertrouwde certificaten die je clientcertificaten die je met verzoeken meestuurt rechtstreeks heeft ondertekend. Je kunt gerust zelfondertekende CA-certificaten gebruiken.
Een certificaat uploaden: een CA-certificaat aan je account toevoegen. Het wordt nog nergens afgedwongen voor mTLS, maar je kunt het al wel configureren.
Scope: een specifiek project of je hele organisatie.
Een CA-certificaat binnen een scope activeren: schakelt mTLS specifiek voor die scope in, en voor alle op API-sleutels gebaseerde verzoeken is een clientcertificaat vereist dat door het CA-certificaat is ondertekend.
Een CA-certificaat binnen een scope deactiveren: schakelt het gebruik van dit certificaat uit om verzoeken binnen deze scope te verifiëren. Als er geen certificaten meer over zijn voor de scope, staat mTLS feitelijk uit.
Een certificaat erven: Als je een certificaat voor je organisatie activeert, wordt het ook voor alle projecten geactiveerd.