Ajout de la prise en charge de mTLS aux déploiements d'API
Découvrez comment utiliser une stratégie de demande pour ajouter la prise en charge de mTLS aux déploiements d'API avec API Gateway.
Les passerelles d'API que vous créez avec le service API Gateway sont sécurisées par le cryptage et la vérification TLS. Une passerelle d'API présente un certificat de serveur à un client d'API lors d'un établissement de liaison TLS, ce qui permet au client d'API de valider l'authenticité de la passerelle d'API. Le processus du client d'API authentifiant la passerelle d'API est appelé TLS unidirectionnel.
Dans de nombreux cas, vous souhaitez uniquement autoriser les clients d'API authentifiés à accéder à une API. Dans ces cas, vous souhaitez que la passerelle d'API valide l'authenticité d'un client d'API en vérifiant le certificat TLS présenté par le client d'API. Le processus de la passerelle d'API authentifiant le client d'API est appelé TLS mutuel (mTLS).
Avec mTLS, la passerelle d'API et le client d'API échangent et vérifient les certificats lors de l'établissement de liaison TLS. La passerelle d'API vérifie le certificat TLS présenté par le client d'API à l'aide de certificats racine d'autorité de certification personnalisée et de packages d'autorité de certification personnalisés de certificats racine et intermédiaires. Les autorités de certification et les packages d'autorité de certification personnalisés sont stockés dans le truststore de la passerelle d'API, ainsi qu'un package d'autorité de certification par défaut contenant les certificats des autorités de certification publiques connues. Dans une procédure d'établissement de liaison mTLS, la passerelle d'API utilise uniquement des autorités de certification et des packages d'autorité de certification personnalisés pour vérifier les certificats de client d'API. La passerelle d'API n'utilise pas le package d'autorité de certification par défaut pour vérifier les certificats de client d'API. Par conséquent, si vous voulez qu'une passerelle d'API prenne en charge mTLS, vous devez ajouter des autorités de certification et des packages d'autorité de certification personnalisés au truststore de la passerelle d'API (reportez-vous à Personnalisation des truststores pour la vérification de certificat TLS).
Pour plus de contrôle, vous pouvez également indiquer que les certificats présentés par les clients API à une passerelle d'API doivent contenir des valeurs particulières dans les champs Adresse électronique, URL ou Nom de domaine du certificat. Si vous indiquez des valeurs pour ces champs lors de la configuration de mTLS pour une passerelle d'API, la passerelle d'API rejettera les demandes des clients d'API présentant des certificats qui ne les contiennent pas. Si vous n'indiquez pas de valeurs pour ces champs lors de la configuration de mTLS, la passerelle d'API acceptera toutes les demandes des clients d'API si le certificat est valide. Vous pouvez indiquer jusqu'à 10 valeurs par défaut pour chaque déploiement d'API (vous pouvez modifier cette limite interne).
Une fois l'établissement de liaison mTLS réussi entre la passerelle d'API et un client d'API, une version codée en Base64 du certificat présenté par le client d'API est enregistrée dans la table de contexte request.cert
en tant que variable de contexte nommée request.cert[client_base64]
. Lors de la définition d'un déploiement d'API, vous pouvez référencer le certificat au format ${request.cert[client_base64]}
(reportez-vous à Ajout de variables de contexte aux stratégies et aux définitions de back-end HTTP). Si un client d'API présente un certificat TLS d'une taille supérieure à 8 Ko (après encodage Base64), le certificat n'est pas enregistré en tant que variable de contexte.
Vous utilisez une stratégie de demande dans la spécification de déploiement d'API pour ajouter la prise en charge de mTLS à une API (reportez-vous à Ajout de stratégies de demande et de réponse aux spécifications de déploiement d'API). La stratégie de demande mTLS s'applique globalement à tous les routages d'une spécification de déploiement d'API.
- Si un client d'API présente un certificat TLS à une passerelle d'API et que le déploiement d'API n'est pas compatible avec le protocole TLS mutuel, la passerelle d'API ignore simplement le certificat TLS présenté. La variable de contexte
request.cert[client_base64]
n'est pas définie dans cette situation. - Si une passerelle d'API ne parvient pas à valider le certificat TLS présenté par un client d'API, elle rejette la demande avec un code de réponse de statut d'erreur HTTP 401.
- Si une passerelle d'API utilise un package d'autorité de certification personnalisé pour valider le certificat TLS présenté par un client d'API, trois certificats d'autorité de certification au maximum peuvent être parcourus à tout moment de la chaîne de certificats pendant la validation. En d'autres termes, pour être valide, un certificat d'autorité de certification dans la chaîne doit être lui-même signé directement par une autorité de certification personnalisée présente dans le truststore de la passerelle d'API, ou ne pas être plus de deux certificats intermédiaires à partir d'un certificat signé par une telle autorité de certification personnalisée. Contactez-nous si vous souhaitez autoriser d'autres certificats intermédiaires.
Vous pouvez ajouter une stratégie de demande mTLS à une spécification de déploiement d'API en :
- utilisant la console,
- modifiant un fichier JSON.
Utilisation de la console pour ajouter des stratégies de demande TLS mutuelle
Pour ajouter une stratégie de demande mTLS à une spécification de déploiement d'API à l'aide de la console, procédez comme suit :
-
Créez ou mettez à jour un déploiement d'API à l'aide de la console, sélectionnez l'option Entièrement nouveau, puis saisissez les détails sur la page Informations de base.
Pour plus d'informations, reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et à Mise à jour d'une passerelle d'API.
-
Dans la section Stratégies de demande d'API de la page Informations de base, sous Mutual-TLS, sélectionnez l'option Activer mTLs et indiquez éventuellement les éléments suivants :
- Autre nom d'objet (SAN) / nom commun : valeurs qui doivent apparaître dans un ou plusieurs des champs suivants du certificat présenté par le client d'API pour que la passerelle d'API accepte les demandes du client :
- Adresse électronique
- URL
- Nom de domaine
Par exemple,
example.com
. Vous pouvez indiquer jusqu'à 10 valeurs par défaut (vous pouvez modifier cette limite interne). La validation ne tient pas compte de la casse.Vous pouvez inclure un caractère générique astérisque (*) au début et/ou à la fin de chaque valeur, pour représenter zéro, un ou plusieurs caractères. Vous ne pouvez pas inclure un caractère générique astérisque au milieu de la valeur. Par exemple :
*.example.com
correspond àserver.example.com
server.example.*
correspond àserver.example.com
*.example.*
correspond àserver.example.com
server.*.com
ne correspond pas àserver.example.com
car le caractère générique ne peut pas se trouver au milieu de la valeur
Si vous indiquez des valeurs lors de la configuration de mTLS pour un déploiement d'API, la passerelle d'API rejettera les demandes des clients d'API présentant des certificats qui ne les contiennent pas. Si vous n'indiquez aucune valeur lors de la configuration de mTLS, la passerelle d'API acceptera toutes les demandes des clients d'API indiquant que le certificat est valide.
- Autre nom d'objet (SAN) / nom commun : valeurs qui doivent apparaître dans un ou plusieurs des champs suivants du certificat présenté par le client d'API pour que la passerelle d'API accepte les demandes du client :
- Sélectionnez Vérifier afin de vérifier les détails saisis pour le déploiement d'API.
- Sélectionnez Créer ou Enregistrer les modifications pour créer ou mettre à jour le déploiement d'API.
- (Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).
Modification d'un fichier JSON pour ajouter des stratégies de demande mTLS
Pour ajouter une stratégie de demande mTLS à une spécification de déploiement d'API dans un fichier JSON, procédez comme suit :
-
A l'aide de l'éditeur JSON de votre choix, modifiez la spécification de déploiement d'API existante à laquelle vous voulez ajouter la prise en charge mTLS ou créez une spécification de déploiement d'API (reportez-vous à Création d'une spécification de déploiement d'API).
Par exemple, la spécification de déploiement d'API de base suivante définit une fonction simple sans serveur Hello World dans OCI Functions en tant que back-end unique :
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Pour indiquer une stratégie de demande mTLS qui s'applique de façon globale à tous les routages d'un déploiement d'API, procédez comme suit :
-
Insérez une section
requestPolicies
avant la sectionroutes
, si elle n'existe pas déjà. Par exemple :{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Ajoutez la stratégie
mutualTLS
suivante à la nouvelle sectionrequestPolicies
pour l'appliquer de façon globale à tous les routages dans un déploiement API :{ "requestPolicies": { "mutualTls":{ "isVerifiedCertificateRequired": true|false, "allowedSans": [<list-of-values>] } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
où :
"isVerifiedCertificateRequired": true|false
esttrue
oufalse
, ce qui indique si mTLS est activé pour le déploiement d'API. Si cette valeur n'est pas renseignée, la valeur par défaut estfalse
."allowedSans": [<list-of-values>]
est une liste facultative de valeurs séparées par des virgules qui doit apparaître dans les champs suivants du certificat présenté par le client d'API pour que la passerelle d'API accepte les demandes du client :- Adresse électronique
- URL
- Nom de domaine
Par exemple,
example.com
. Vous pouvez indiquer jusqu'à 10 valeurs par défaut (vous pouvez modifier cette limite interne). La validation ne tient pas compte de la casse.Vous pouvez inclure un caractère générique astérisque (*) au début et/ou à la fin de chaque valeur, pour représenter zéro, un ou plusieurs caractères. Vous ne pouvez pas inclure un caractère générique astérisque au milieu de la valeur. Par exemple :
*.example.com
correspond àserver.example.com
server.example.*
correspond àserver.example.com
*.example.*
correspond àserver.example.com
server.*.com
ne correspond pas àserver.example.com
car le caractère générique ne peut pas se trouver au milieu de la valeur
Si vous indiquez des valeurs lors de la configuration de mTLS pour un déploiement d'API, la passerelle d'API rejettera les demandes des clients d'API présentant des certificats qui ne les contiennent pas. Si vous n'indiquez aucune valeur lors de la configuration de mTLS, la passerelle d'API acceptera toutes les demandes des clients d'API indiquant que le certificat est valide.
Par exemple :
{ "requestPolicies": { "mutualTls":{ "isVerifiedCertificateRequired": true, "allowedSans": [ "example.com", "example.co.uk" ] } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
- Enregistrez le fichier JSON qui contient la spécification de déploiement d'API.
-
Utilisez la spécification de déploiement d'API lorsque vous créez ou mettez à jour un déploiement d'API en :
- spécifiant le fichier JSON dans la console lorsque vous sélectionnez l'option Télécharger une API existante,
- spécifiant le fichier JSON dans une demande adressée à l'API REST d'API Gateway.
Pour plus d'informations, reportez-vous à Déploiement d'une API sur une passerelle d'API en créant un déploiement d'API et à Mise à jour d'une passerelle d'API.
- (Facultatif) Vérifiez que l'API a été déployée en l'appelant (reportez-vous à Appel d'une API déployée sur une passerelle d'API).