Met OpenAI Mutual TLS kunnen organisaties een extra beveiligingslaag configureren voor hun OpenAI API-verkeer. Na configuratie moeten API-aanvragen worden gedaan naar https://mtls.api.openai.com (of https://mtls-eu.api.openai.com voor EU-klanten met gegevensresidentie) en wordt verkeer alleen geaccepteerd als de juiste API-sleutel en het juiste clientcertificaat worden verstrekt. mTLS is niet van toepassing op het https://platform.openai.com-dashboard. Deze functie bevindt zich momenteel in bèta.
Hoe stel ik de mTLS-integratie in?
Op de navigatiebalk voor instellingen zie je een tabblad ‘Wederzijdse TLS’.
Certificaat uploaden
Certificaat activeren
Nadat je je certificaat hebt geüpload, is de volgende stap om je certificaat te activeren. Zodra een certificaat voor een project is geactiveerd, vereisen alle API-aanvragen 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, is het van toepassing op alle API-aanvragen en wordt het door alle projecten ‘overgeërfd’.
Vereisten voor CA-certificaten
Je kunt elk X.509-CA-certificaat in PEM-indeling uploaden dat aan de volgende vereisten voldoet:
ondertekent rechtstreeks de clientcertificaten die je wilt gebruiken, of fungeert als anker voor een geldige certificaatketen die je client presenteert.
heeft de extensies Certificate Authority, Subject Key Identifier en Authority Key Identifier (in KeyIdentifier-indeling)
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
Als ondersteuning voor certificaatketens is ingeschakeld voor je organisatie, kan je client een leaf-clientcertificaat presenteren met de tussencertificaten die nodig zijn om een geldige keten op te bouwen naar een actief geüpload certificaat. Anders moeten clientcertificaten rechtstreeks zijn ondertekend door certificaten die je vooraf hebt geüpload. Daarnaast moeten je clientcertificaten aan de volgende vereisten voldoen:
heeft de extensies Subject Key Identifier en Authority Key Identifier (in KeyIdentifier-indeling)
heeft de Key Usage-machtigingen: “Digital Signature, Key Encipherment”
heeft de Extended Key Usage-machtiging: “TLS Web Client Authentication”
heeft de extensie Subject Alternate Name
Ondersteuning voor certificaatketens voor API-mTLS
Met ondersteuning voor certificaatketens kan je client een leaf-clientcertificaat presenteren met de tussencertificaten die nodig zijn om een geldige keten op te bouwen naar een actief geüpload certificaat.
Hiermee kun je tussencertificaten roteren zonder elke nieuwe intermediate te uploaden, zolang het actief geüploade certificaat dat als vertrouwensanker wordt gebruikt geldig blijft.
Ondersteuning voor certificaatketens is momenteel op aanvraag beschikbaar. Neem contact op met je Account Director of open een supportticket om toegang aan te vragen.
Je client moet alle vereiste tussencertificaten presenteren. OpenAI haalt ontbrekende tussencertificaten niet op via AIA. CRL- en OCSP-controles blijven niet ondersteund.
Veelgestelde vragen
Kan ik mTLS via de API configureren?
Ja — raadpleeg de API-referentie op https://platform.openai.com/docs/api-reference/ voor meer informatie.
Welke endpoints ondersteunen mTLS?
Tijdens deze bètaperiode wordt mTLS officieel ondersteund in
/v1/chat/completions (with all supported extensions e.g. image, audio, streaming, etc.)/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 web sockets)/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 manpagina 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 voorbeeld in Python.
Wanneer ondersteuning voor certificaatketens is ingeschakeld, configureer je HTTP-client dan zo dat deze het leaf-clientcertificaat en alle vereiste tussencertificaten presenteert. De exacte configuratie hangt af van je HTTP-client.
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). Let op: onze server verstrekt geen certificate_authorities-lijst in het verzoek om een clientcertificaat.
Wie heeft toegang tot certificaten en kan ze wijzigen?
Via de Dashboard-UI op https://platform.openai.com/settings/organization/mtls kunnen eigenaars van de organisatie certificaten openen en wijzigen. Iedereen met een Admin API Key (https://platform.openai.com/settings/organization/admin-keys) kan ook certificaten openen/wijzigen, maar let op — als je Mutual TLS op organisatieniveau activeert, dwing je certificaten ook af voor deze API-aanvragen. Alle mTLS-wijzigingen zijn zichtbaar in auditlogs.
Hoeveel certificaten kan ik hebben?
Elke organisatie kan maximaal 50 certificaten uploaden. Deze kunnen worden gedeeld tussen projecten, maar niet met andere organisaties. Je kunt een certificaat atomair activeren/deactiveren voor 10 projecten tegelijk. 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 niet actief zijn binnen een bereik.
Hoe werkt certificaatintrekking?
Op dit moment ondersteunen we geen CRL- of OCSP-controles. 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 met kortere geldigheidsperioden gebruiken.
Kan ik langere certificaatketens gebruiken?
Ja, als ondersteuning voor certificaatketens is ingeschakeld voor je organisatie. Je client moet het leaf-clientcertificaat en alle vereiste tussencertificaten presenteren, zodat OpenAI de keten kan verifiëren tot aan een actief geüpload certificaat. Neem contact op met je Account Director of open een supportticket om toegang aan te vragen.
Wat is de aanbevolen configuratie?
Bij het voor het eerst instellen van deze functie raden we aan te beginnen met een stagingproject dat geen officieel productieverkeer verwerkt. Gebruik deze gelegenheid om te controleren of je certificaten correct zijn ingesteld op je machines en of je succesvol API-verkeer kunt versturen. Daarnaast raden we aan om met het beveiligingsteam van je organisatie te overleggen om je behoeften beter te begrijpen.
Extra ondersteuning
Je kunt de mTLS-functie volledig zelf beheren via het dashboard en de API. Als je mTLS echter eerst in een schaduwmodus 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 wordt gebruikt om clientcertificaten te verifiëren. Het kan de clientcertificaten die je met verzoeken meestuurt rechtstreeks ondertekenen, of dienen als anker voor een certificaatketen die je client presenteert. Je kunt zelfondertekende CA-certificaten gebruiken.
Een certificaat uploaden: een CA-certificaat toevoegen aan je account. Het wordt nog nergens afgedwongen voor mTLS, maar je kunt het alvast configureren.
Bereik: een specifiek project of je hele organisatie.
Een CA-certificaat activeren voor een bereik: schakelt mTLS specifiek in voor dat bereik, waarna alle verzoeken op basis van een API-sleutel een clientcertificaat moeten bevatten dat kan worden geverifieerd aan de hand van het actieve CA-certificaat.
Een CA-certificaat deactiveren voor een bereik: schakelt het gebruik van dit certificaat uit voor het verifiëren van verzoeken binnen dit bereik. Als er geen certificaten meer over zijn voor het bereik, is mTLS effectief uitgeschakeld.
Een certificaat overerven: als je een certificaat voor je organisatie activeert, wordt het ook voor alle projecten geactiveerd.