TLS mutuel

Le TLS mutuel (mTLS) ajoute une vérification du certificat client TLS aux requêtes adressées à l’API OpenAI. Une fois que vous avez activé un certificat de confiance pour une organisation ou un projet, toute requête relevant de cette organisation ou de ce projet doit présenter un certificat client accepté en plus de ses identifiants Bearer habituels.

Utilisez mTLS lorsqu’une charge de travail peut conserver une clé privée client en toute sécurité et que vous souhaitez qu’OpenAI vérifie l’identité attestée par son certificat avant d’autoriser une requête API. mTLS ne remplace ni les clés API, ni les identifiants de compte de service, ni les jetons d’accès associés aux identités des charges 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 à une identité de lister, de consulter et de tester les paramètres des certificats.
• api.mtls.write permet à une identité d’importer, de modifier, d’activer, de désactiver et de supprimer des certificats.

Le rôle de propriétaire de l’organisation inclut ces autorisations. Vous pouvez également les accorder au moyen d’un rôle personnalisé. Pour en savoir plus, consultez le guide Gérer 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.
• Les certificats intermédiaires nécessaires pour établir une chaîne entre le certificat client et votre ancre de confiance.
• Une ancre de confiance stable au format PEM, que vous pouvez activer au niveau de l’organisation ou du projet.
• Un projet non critique et une procédure de reprise testée avant d’activer mTLS pour le trafic de production.

Conservez les clés privées en dehors du système de gestion de versions. Ne consignez dans les journaux ni les clés privées, ni le contenu des certificats, ni les identifiants Bearer.

Importation et activation des ancres de confiance

L’importation enregistre le certificat. C’est son activation qui rend mTLS obligatoire pour les requêtes concernées.

1. Ouvrez Paramètres de l’organisation > Sécurité > TLS mutuel.
2. Importez une ancre de confiance au format PEM par objet certificat. Donnez-lui un nom qui permet d’identifier l’autorité et de distinguer les générations successives lors des rotations.
3. Si nécessaire, ajoutez un filtre CEL pour limiter les certificats clients vérifiés que cette ancre peut accepter.
4. Activez d’abord le certificat pour un projet non critique. Depuis chaque charge de travail prévue, envoyez des requêtes représentatives à un hôte mTLS de l’API.
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 identifiants disposant de l’autorisation requise, api.mtls.read ou api.mtls.write. Pour connaître les schémas des requêtes et des réponses, consultez la référence de l’API de gestion des certificats d’organisation.

Exigences relatives aux certificats

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

Pour qu’une requête passe la vérification mTLS, les conditions suivantes doivent être remplies :

• Le certificat client doit être valide au moment de la requête et adapté à l’authentification du client TLS.
• Il doit être possible d’établir une chaîne valide entre le certificat client et une ancre de confiance active au niveau de l’organisation ou du projet.
• Si la chaîne comporte 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 présentée par le client doivent satisfaire aux règles standard de validation des chaînes de certificats clients X.509.

Si le fichier importé contient plusieurs certificats au format PEM, la vérification de la chaîne présentée avec la requête utilise uniquement le premier certificat configuré comme ancre. Ne comptez pas sur la prise en charge de l’ensemble des certificats du fichier PEM.

OpenAI ne récupère pas les certificats intermédiaires manquants à partir des URL de l’extension Authority Information Access (AIA) et ne vérifie pas la révocation des certificats au moyen des listes de révocation de certificats (CRL) ou du protocole OCSP (Online Certificate Status Protocol). Présentez la chaîne requise dans son intégralité. En cas d’incident, utilisez la rotation ou la désactivation des certificats ainsi que vos propres mécanismes de gestion de leur cycle de vie.

Ordre des vérifications

OpenAI vérifie les certificats actifs du projet avant ceux de l’organisation. Si aucun certificat n’est actif ni pour le projet ni pour l’organisation, mTLS n’ajoute aucune vérification de certificat à la requête.

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

1. OpenAI tente d’abord la vérification directe habituelle du certificat client auprès d’une ancre active, sans utiliser les certificats intermédiaires de la requête.
2. Si cette vérification directe ne trouve aucune correspondance et ne rencontre pas d’autre erreur, OpenAI tente de vérifier la chaîne à l’aide du certificat client et des certificats intermédiaires présentés lors de la connexion TLS.
3. Si la chaîne est valide, OpenAI applique au certificat client vérifié le filtre CEL du certificat actif, le cas échéant.

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

OpenAI se rabat sur cette chaîne lorsque la vérification directe ne trouve simplement aucune correspondance. D’autres erreurs de vérification directe peuvent entraîner le rejet de la requête sans examen de la chaîne présentée. C’est le cas si des données de certificat sont manquantes ou mal formées, si l’AKI est absent ou si une erreur déterministe survient après la sélection d’une ancre lors de la vérification directe.

Filtrage des certificats clients avec CEL

Vous pouvez associer un filtre Common Expression Language (CEL) à un certificat importé pour limiter les certificats clients vérifiés que cette ancre accepte. L’expression doit renvoyer un booléen. Elle s’applique au certificat client vérifié, que la vérification soit directe ou qu’elle utilise la chaîne présentée avec la requête.

CEL donne accès aux 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 chaque entrée contient les champs type, value et oid. Les identifiants de type SAN pris en charge sont DNS, EMAIL, IP_ADDRESS, URI et CUSTOM.

Par exemple, pour exiger que le certificat indique l’unité organisationnelle de production et comporte un nom alternatif du sujet (SAN) de type DNS dans un espace de noms précis, utilisez l’expression suivante :

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

Si le certificat est valide mais ne satisfait pas au filtre, la requête échoue avec le code certificate_attribute_verification_failed. Lors de l’enregistrement, OpenAI rejette toute règle qui échoue à la validation.

Utilisation d’un hôte mTLS

Envoyez les requêtes API à un hôte mTLS au lieu de api.openai.com.

La prise en charge de mTLS dépend de l’hôte. Utilisez la même route /v1 que pour l’interface API correspondante et testez chaque API et chaque modèle que votre charge de travail utilise. Les routes et les modèles disponibles peuvent varier d’un hôte régional à l’autre.

Par exemple, envoyez vos identifiants Bearer habituels 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"

Dans le fichier de chaîne de certificats, placez d’abord le certificat client, puis les é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 charges de travail avec X.509 utilise un point de terminaison d’échange distinct, dont l’adresse exacte est POST https://mtls.auth.openai.com/oauth/token. Cet échange produit un jeton Bearer de courte durée. Le certificat seul ne suffit pas pour s’authentifier auprès de l’API. Pour connaître la structure complète de la requête, consultez la référence sur l’échange de jetons d’identité de charge de travail.

Rotation des certificats

Lors de la rotation, prévoyez une période pendant laquelle les deux ancres de confiance sont actives pour que les charges de travail existantes continuent de fonctionner.

1. Importez la nouvelle ancre de confiance en laissant l’ancienne active.
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 aboutit à la nouvelle ancre. Testez ensuite 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 utilisent la nouvelle.
5. Ne supprimez l’ancien certificat qu’après l’avoir désactivé pour l’organisation et pour chacun de ses projets.

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.

Diagnostic des échecs de requêtes

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

Pour les requêtes de gestion, mtls_certificate_invalid indique que le fichier PEM importé a échoué à la validation. Le code expired_certificate indique que le certificat expire trop tôt ou a déjà expiré. Le code mtls_cel_policy_invalid indique que le filtre a échoué à la validation. Le code 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 une vérification du certificat à l’authentification habituelle auprès de l’API. Le certificat seul ne suffit pas pour autoriser une requête API.
• OpenAI ne récupère pas les certificats intermédiaires via AIA et n’effectue aucune vérification au moyen de CRL ou d’OCSP.
• Private Link est incompatible avec mTLS. Consultez le guide Private Link si vous avez besoin d’une connexion via un réseau privé Azure.
• Les hôtes mTLS pris en charge pour l’API sont mtls.api.openai.com, mtls-us.api.openai.com et mtls-eu.api.openai.com. Ne partez pas du principe que chaque autre hôte régional de l’API dispose d’un équivalent mTLS.
• La fédération d’identités de charges de travail avec X.509 ne renvoie aucun jeton de renouvellement et n’utilise ni DPoP, ni attribut cnf, ni jeton Bearer lié à un certificat. Consultez le guide Configurer la fédération d’identités de charges de travail avec des certificats X.509.