TLS mutuel

Le TLS mutuel (mTLS) ajoute la vérification des certificats clients TLS aux requêtes à l’API OpenAI. Une fois un certificat de confiance activé pour une organisation ou un projet, les requêtes relevant de ce périmètre doivent présenter un certificat client accepté en plus de leurs informations d’authentification de type bearer habituelles.

Utilisez mTLS lorsqu’une charge de travail peut conserver une clé privée cliente de manière sécurisée et que vous souhaitez qu’OpenAI vérifie l’identité portée par son certificat avant d’autoriser une requête à l’API. mTLS ne remplace pas les clés API, les informations d’authentification des comptes de service ni les jetons d’accès associés aux identités de charge de travail.

Avant de configurer mTLS

Toute organisation utilisant l’API peut gérer mTLS au moyen du contrôle d’accès basé sur les rôles (RBAC) habituel :

• api.mtls.read permet à un principal de lister, de consulter et de tester les paramètres des certificats.
• api.mtls.write permet à un principal d’importer, de mettre à jour, d’activer, de désactiver et de supprimer des certificats.

Le rôle de propriétaire de l’organisation inclut ces autorisations, mais vous pouvez aussi les accorder au moyen d’un rôle personnalisé. Pour en savoir plus, consultez Gérez les autorisations sur la plateforme OpenAI.

Préparez les éléments suivants :

• Un certificat client et sa clé privée pour chaque charge de travail.
• Tous les certificats intermédiaires nécessaires pour construire un chemin du certificat client jusqu’à votre ancre de confiance.
• Une ancre de confiance stable, encodée au format PEM, que vous pouvez activer au niveau de l’organisation ou du projet.
• Un projet non critique et une procédure de récupération testée avant d’activer mTLS pour le trafic de production.

Conservez les clés privées hors du système de gestion de versions. Ne consignez pas les clés privées, le contenu des certificats ni les informations d’authentification de type bearer dans les journaux.

Importez et activez les ancres de confiance

L’importation enregistre un certificat, mais ne rend pas mTLS obligatoire. C’est l’activation qui modifie le traitement des requêtes.

1. Ouvrez Paramètres de l’organisation > Sécurité > TLS mutuel.
2. Importez une ancre de confiance encodée au format PEM pour chaque objet certificat. Donnez-lui un nom qui identifie l’autorité et la génération de rotation.
3. Si vous le souhaitez, ajoutez un filtre CEL qui limite les certificats clients vérifiés que cette ancre peut accepter.
4. Activez d’abord le certificat pour un projet non critique. Envoyez des requêtes représentatives via un hôte d’API mTLS depuis chaque charge de travail prévue.
5. Une fois la validation réussie, activez le certificat pour les autres projets ou pour l’organisation.

Vous pouvez également gérer les certificats via l’API :

Utilisez des informations d’authentification disposant de l’autorisation requise, api.mtls.read ou api.mtls.write. Pour les schémas des requêtes et des réponses, consultez la référence de l’API des certificats de l’organisation.

Exigences relatives aux certificats

Utilisez une ancre de confiance encodée au format PEM par objet certificat. Le fichier importé doit contenir un certificat valide qui expire plus d’un jour après l’importation. Le certificat client doit inclure un identifiant de clé d’autorité (AKI) pour permettre la vérification des requêtes.

Pour qu’une requête passe la vérification mTLS :

• Le certificat client doit être valide au moment de la requête et adapté à l’authentification des clients TLS.
• Le certificat client doit permettre de construire un chemin valide jusqu’à une ancre de confiance active au niveau de l’organisation ou du projet.
• Si le chemin comprend des certificats intermédiaires, le client doit les présenter lors de la négociation TLS.
• L’ancre de confiance configurée et la chaîne du client doivent satisfaire à la validation standard des chemins de certification client X.509.

Si un fichier importé contient plusieurs certificats encodés au format PEM, la vérification de la chaîne présentée dans la requête utilise uniquement le premier certificat configuré comme ancre ; ne vous appuyez pas sur le fonctionnement habituel des ensembles de certificats PEM.

OpenAI ne récupère pas les certificats intermédiaires manquants depuis les URL Authority Information Access (AIA) et n’effectue aucune vérification des listes de révocation de certificats (CRL) ni via le protocole Online Certificate Status Protocol (OCSP). Présentez la chaîne requise complète et gérez la réponse aux incidents au moyen de la rotation et de la désactivation des certificats, ainsi que de vos propres contrôles du cycle de vie des certificats.

Comprenez l’ordre des vérifications

OpenAI vérifie les certificats actifs au niveau du projet avant ceux actifs au niveau de l’organisation. Si aucun de ces deux périmètres ne dispose d’un certificat actif, mTLS n’ajoute aucune vérification de certificat à la requête.

Lorsqu’un certificat actif existe, OpenAI vérifie l’identité du client dans l’ordre suivant :

1. OpenAI tente d’abord la vérification directe existante, qui vérifie le certificat client directement par rapport à une ancre active, sans utiliser les certificats intermédiaires de la requête.
2. Si la vérification directe ne trouve simplement aucune correspondance, OpenAI tente de vérifier la chaîne de la requête à l’aide du certificat client et des certificats intermédiaires présentés par la connexion TLS.
3. Si un chemin est validé, OpenAI évalue le filtre CEL du certificat actif, s’il est défini, sur le certificat client vérifié.

La vérification de la chaîne présentée dans la requête est disponible par défaut.

La vérification de la chaîne présentée dans la requête sert de solution de repli lorsqu’aucune correspondance n’est trouvée ; elle ne permet pas de récupérer après toutes les erreurs de vérification directe. Des données de certificat manquantes ou mal formées, un AKI absent ou une erreur déterministe survenant après la sélection d’une ancre par la vérification directe peuvent faire échouer la requête sans tentative de vérification de la chaîne présentée.

Filtrez les certificats clients avec CEL

Associez un filtre Common Expression Language (CEL) facultatif à un certificat importé pour limiter les certificats clients vérifiés que cette ancre accepte. L’expression doit renvoyer un booléen et s’applique au certificat client vérifié, aussi bien lors de la vérification directe que lors de la vérification de la chaîne présentée dans la requête.

CEL expose les champs suivants :

• subject.common_name, subject.country_code, subject.organization, subject.organizational_unit, subject.locality, subject.province, subject.street_address et subject.postal_code.
• subject_alt_names, une liste dont les entrées exposent type, value et oid. Les identifiants de type SAN pris en charge sont DNS, EMAIL, IP_ADDRESS, URI et CUSTOM.

Par exemple, exigez une unité organisationnelle de production et un SAN de type DNS dans un espace de noms spécifique :

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

Un certificat dont la vérification réussit mais qui ne satisfait pas au filtre entraîne l’erreur certificate_attribute_verification_failed. OpenAI rejette toute politique qui échoue à la validation au moment de son enregistrement.

Utilisez un hôte mTLS

Envoyez le trafic de l’API vers un hôte mTLS plutôt que vers api.openai.com :

mTLS fonctionne au niveau de l’hôte. Utilisez la même route /v1 que sur l’interface API correspondante, et testez chaque API et chaque modèle utilisés par votre charge de travail. La disponibilité des routes et des modèles peut varier selon les hôtes régionaux.

Par exemple, envoyez un token porteur habituel et un certificat client à l’hôte mTLS par défaut :

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"

Le fichier de chaîne de certificats doit contenir le certificat client en premier, suivi des éventuels certificats intermédiaires requis. N’envoyez pas de données de certificat dans les en-têtes HTTP ni dans le corps des requêtes.

La fédération d’identités de charge de travail X.509 utilise un point de terminaison d’échange distinct, à cette adresse précise : POST https://mtls.auth.openai.com/oauth/token. Cet échange produit un token porteur de courte durée ; il ne permet pas de s’authentifier auprès de l’API avec un certificat seul. Pour connaître la structure complète de la requête, consultez la référence de l’échange de tokens d’identité de charge de travail.

Rotation des certificats

Prévoyez une période de chevauchement lors de la rotation des ancres de confiance pour que les charges de travail existantes continuent de fonctionner :

1. Importez la nouvelle ancre de confiance sans désactiver l’ancienne.
2. Activez la nouvelle ancre dans chaque projet concerné ou au niveau de l’organisation.
3. Mettez à jour les charges de travail pour qu’elles présentent des certificats clients dont la chaîne mène à la nouvelle ancre, puis testez chaque hôte mTLS et chaque interface API qu’elles utilisent.
4. Désactivez l’ancienne ancre une fois que toutes les charges de travail ont migré.
5. Supprimez l’ancien certificat uniquement après l’avoir désactivé pour l’organisation et pour chaque projet.

Vous pouvez renouveler les certificats intermédiaires sans modifier l’ancre de confiance configurée. Présentez la nouvelle chaîne complète lors des requêtes suivantes.

Résolution des problèmes de requêtes

Utilisez les codes d’erreur stables pour distinguer les erreurs de configuration des erreurs temporaires du service :

Pour les requêtes de gestion, mtls_certificate_invalid indique que le certificat PEM importé n’a pas passé la validation, expired_certificate indique qu’il expire trop tôt ou qu’il a expiré, mtls_cel_policy_invalid indique que le filtre ne passe pas la validation, et certificate_in_use indique que vous devez désactiver le certificat avant de le supprimer.

Limites actuelles

• Une organisation peut importer jusqu’à 50 objets certificat.
• mTLS ajoute la vérification des certificats à l’authentification habituelle de l’API ; il ne permet pas d’autoriser l’accès à l’API sur la seule base d’un certificat.
• OpenAI ne récupère pas les certificats intermédiaires via AIA et n’effectue pas de vérifications CRL ou OCSP.
• Private Link n’est pas compatible avec mTLS. Consultez Private Link si vous avez plutôt besoin d’un accès via un réseau privé Azure.
• Les hôtes mTLS de l’API pris en charge sont mtls.api.openai.com, mtls-us.api.openai.com et mtls-eu.api.openai.com. Ne supposez pas que tous les autres hôtes régionaux de l’API disposent d’un équivalent mTLS.
• La fédération d’identités de charge de travail X.509 ne renvoie pas de token d’actualisation et n’utilise ni DPoP, ni attribut cnf, ni token porteur lié à un certificat. Consultez Configuration de la fédération d’identités de charge de travail avec des certificats X.509.