Comment activer l'authentification TLS mutuelle pour votre REST APIs dans API Gateway

L’authentification TLS mutuelle nécessite une authentification bidirectionnelle entre le client et le serveur. Avec l’authentification TLS mutuelle, les clients doivent présenter des certificats X.509 pour vérifier leur identité afin d’accéder à votre API. Le protocole TLS mutuel est une exigence courante pour l'Internet des objets (IoT) et business-to-business les applications.

Vous pouvez utiliser l’authentification TLS mutuelle avec d’autres opérations d’autorisation et d’authentification prises en charge par API Gateway. API Gateway transmet les certificats que les clients fournissent aux mécanismes d’autorisation Lambda et aux intégrations de backend.

Conditions préalables pour l’authentification TLS mutuelle

Pour configurer des authentifications TLS mutuelles, vous avez besoin des éléments suivants :

Noms de domaine personnalisés

Pour activer l’authentification TLS mutuelle pour une API REST, vous devez configurer un nom de domaine personnalisé pour votre API. Vous pouvez activer l’authentification TLS mutuelle pour un nom de domaine personnalisé, puis fournir le nom de domaine personnalisé aux clients. Pour accéder à une API à l’aide d’un nom de domaine personnalisé sur lequel l’authentification TLS mutuelle est activée, les clients doivent présenter des certificats approuvés dans les demandes d’API. Vous trouverez plus d’informations dans Nom de domaine personnalisé pour le REST public APIs dans API Gateway.

Utilisation de certificats AWS Certificate Manager émis

Vous pouvez demander un certificat approuvé publiquement directement à partir d’ACM ou importer des certificats publics ou auto-signés. Pour configurer un certificat dans ACM, accédez à ACM. Si vous souhaitez importer un certificat, poursuivez votre lecture dans la section suivante.

Utilisation d'un AWS Private Certificate Authority certificat ou d'un produit importé

Pour utiliser un certificat importé dans ACM ou un certificat provenant AWS Private Certificate Authority d'un protocole TLS mutuel, API Gateway a besoin d'un certificat ownershipVerificationCertificate émis par ACM. Ce certificat de propriété est utilisé uniquement pour vérifier que vous disposez des autorisations nécessaires pour utiliser le nom de domaine. Il n’est pas utilisé pour la poignée de main TLS. Si vous n'en avez pas encoreownershipVerificationCertificate, rendez-vous sur https://console.aws.amazon.com/acm/pour en créer un.

Vous devrez conserver ce certificat valide pendant toute la durée de vie de votre nom de domaine. Si un certificat expire et que le renouvellement automatique échoue, toutes les mises à jour du nom de domaine seront verrouillées. Vous devrez mettre à jour le ownershipVerificationCertificateArnavec un ownershipVerificationCertificate valide avant de pouvoir effectuer d’autres modifications. Le ownershipVerificationCertificate ne peut pas être utilisé comme certificat de serveur pour un autre domaine TLS mutuel dans API Gateway. Si un certificat est directement réimporté dans ACM, le diffuseur doit rester le même.

Configuration de votre magasin de confiance

Les magasins de confiance sont des fichiers texte avec une .pem extension de fichier. Il s’agit d’une liste de certificats approuvés provenant des autorités de certification. Pour utiliser l’authentification TLS mutuelle, créez un magasin de confiance de certificats X.509 auxquels vous faites confiance pour accéder à votre API.

Vous devez inclure la chaîne de confiance complète à partir du certificat de l’autorité de certification émettrice jusqu’au certificat de l’autorité de certification racine, dans votre magasin de confiance. API Gateway accepte les certificats clients émis par toute autorité de certification présente dans la chaîne de confiance. Les certificats peuvent être délivrés par des autorités de certification publiques ou privées. Les certificats peuvent avoir une longueur de chaîne maximale de quatre. Vous pouvez également fournir des certificats auto-signés. Les algorithmes suivants sont pris en charge dans le magasin de confiance :

API Gateway valide un certain nombre de propriétés de certificat. Vous pouvez utiliser des mécanismes d’autorisation Lambda pour effectuer des vérifications supplémentaires lorsqu’un client appelle une API, notamment pour vérifier si un certificat a été révoqué. API Gateway valide les propriétés suivantes :

Chargement du magasin de confiance dans un fichier unique d’un compartiment Amazon S3

Un fichier .pem devrait ressembler à l’exemple suivant.

-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Certificate contents>
-----END CERTIFICATE-----
...

La AWS CLI commande cp suivante est chargée dans certificates.pem votre compartiment Amazon S3 :

aws s3 cp certificates.pem s3://bucket-name

Configuration de l’authentification TLS mutuelle pour un nom de domaine personnalisé

Pour configurer l’authentification TLS mutuelle pour une API REST, vous devez utiliser un nom de domaine personnalisé régional pour votre API, avec une politique de sécurité TLS_1_2. Pour plus d’informations sur le choix d’une politique de sécurité, consultez Sélection d’une politique de sécurité pour le domaine personnalisé de votre API REST dans API Gateway.

Une fois que vous avez chargé votre magasin de confiance dans Amazon S3, vous pouvez configurer votre nom de domaine personnalisé pour utiliser l’authentification TLS mutuelle. Ce qui suit create-domain-namecrée un nom de domaine personnalisé avec le protocole TLS mutuel :

aws apigateway create-domain-name --region us-east-2 \
    --domain-name api.example.com \
    --regional-certificate-arn arn:aws:acm:us-east-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --endpoint-configuration types=REGIONAL \
    --security-policy TLS_1_2 \
    --mutual-tls-authentication truststoreUri=s3://bucket-name/key-name

Après avoir créé le nom de domaine, vous devrez configurer des enregistrements DNS et des mappages de chemin de base pour les opérations API. Pour en savoir plus, consultez la section Configuration d’un nom de domaine personnalisé régional dans API Gateway.

Appeler une API à l’aide d’un nom de domaine personnalisé qui nécessite une authentification TLS mutuelle

Pour appeler une API avec l’authentification TLS mutuelle activée, les clients doivent présenter un certificat approuvé dans la demande d’API. Lorsqu’un client tente d’appeler votre API, API Gateway recherche le diffuseur du certificat client dans votre magasin de confiance. Pour que l’API Gateway puisse poursuivre la demande, le diffuseur du certificat et la chaîne de confiance complète jusqu’au certificat d’autorité de certification racine doivent se trouver dans votre magasin de confiance.

L’exemple de commande curl suivant envoie à api.example.com, une demande qui inclut my-cert.pem dans la demande. my-key.key est la clé privée du certificat.

curl -v --key ./my-key.key --cert ./my-cert.pem api.example.com

Votre API est appelée uniquement si votre magasin de confiance approuve le certificat. Les conditions suivantes provoqueront l’échec de la poignée de main de l’API Gateway avec TLS et le refus de la demande d’un code de statut 403. Si votre certificat :

Mise à jour de votre magasin de confiance

Pour mettre à jour les certificats dans votre magasin de confiance, chargez un nouveau lot de certificats dans Amazon S3. Vous pourrez ensuite mettre à jour votre nom de domaine personnalisé de manière à utiliser le certificat mis à jour.

Utilisez la gestion des versions Amazon S3 pour gérer plusieurs versions de votre magasin de confiance. Lorsque vous mettez à jour votre nom de domaine personnalisé de manière à utiliser une nouvelle version du magasin de confiance, API Gateway renvoie des avertissements si les certificats ne sont pas valides.

API Gateway ne génère des avertissements de certificat que lorsque vous mettez à jour votre nom de domaine. API Gateway ne vous avertit pas si un certificat précédemment chargé arrive à expiration.

La update-domain-namecommande suivante met à jour un nom de domaine personnalisé afin d'utiliser une nouvelle version de Truststore :

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='abcdef123'

Désactiver l’authentification TLS mutuelle

Ce qui suit update-domain-namedésactive le protocole TLS mutuel :

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

Résolution des problèmes d’authentification TLS mutuelle pour votre API REST

Les rubriques suivantes fournissent des conseils de dépannage pour les erreurs et problèmes que vous pouvez rencontrer lorsque vous activez l’authentification TLS mutuelle.

Résolution des problèmes liés aux avertissements de certificat

Lors de la création d’un nom de domaine personnalisé avec authentification TLS mutuelle, API Gateway renvoie des avertissements si les certificats du magasin de confiance ne sont pas valides. Cela peut également se produire lors de la mise à jour d’un nom de domaine personnalisé de manière à utiliser un nouveau magasin de confiance. Les avertissements indiquent le problème lié au certificat et l’objet du certificat ayant produit l’avertissement. L’authentification TLS mutuelle reste activée pour votre API, mais certains clients risquent de ne pas être en mesure d’accéder à votre API.

Vous devrez décoder les certificats de votre magasin de confiance pour identifier le certificat ayant émis l’avertissement. Vous pouvez utiliser des outils tels que openssl pour décoder les certificats et identifier leur objet.

La commande suivante affiche le contenu d’un certificat, y compris son objet.

openssl x509 -in certificate.crt -text -noout

Mettez à jour ou supprimez les certificats ayant produit des avertissements, puis chargez un nouveau magasin de confiance dans Amazon S3. Après avoir chargé le nouveau magasin de confiance, mettez à jour votre nom de domaine personnalisé de manière à utiliser le nouveau magasin de confiance.

Résolution des conflits de noms de domaine

L’erreur "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." signifie que plusieurs autorités de certification ont émis un certificat pour ce domaine. Pour chaque sujet du certificat, il ne peut y avoir qu’un seul diffuseur dans API Gateway pour les domaines TLS mutuels. Vous devrez obtenir tous vos certificats pour ce sujet par l’intermédiaire d’un seul diffuseur. Si le problème est dû à un certificat dont vous n’avez pas le contrôle, mais pour lequel vous pouvez prouver la propriété du nom de domaine, contactez Support pour ouvrir un ticket.

Dépannage des messages d’état des noms de domaine

PENDING_CERTIFICATE_REIMPORT: Cela signifie que vous avez réimporté un certificat dans ACM et que sa validation a échoué car le nouveau certificat possède un SAN (nom alternatif du sujet) qui n'est pas couvert par le ownershipVerificationCertificate ou le sujet ou SANs le certificat ne couvre pas le nom de domaine. Quelque chose peut être configuré de manière incorrecte ou un certificat non valide a été importé. Vous devez réimporter un certificat valide dans ACM. Pour en savoir plus sur la validation, consultez Validation de la propriété de domaine.

PENDING_OWNERSHIP_VERIFICATION : cela signifie que votre certificat précédemment vérifié a expiré et qu’ACM n’a pas pu le renouveler automatiquement. Vous devrez renouveler le certificat ou demander un nouveau certificat. Vous trouverez des informations supplémentaires sur le renouvellement du certificat dans le guide : Résolution des problèmes dus au renouvellement des certificats gérés d’ACM.

Résolution des problèmes liés au renvoi d’un certificat incorrect

Lors de la migration d’un certificat dédié d’un nom de domaine complet vers un nom de domaine client générique, API Gateway peut renvoyer le certificat du nom de domaine complet au lieu du nom de domaine générique.

La commande suivante indique le certificat qui est renvoyé par API Gateway :

openssl s_client -connect hostname:port

Si le certificat obtenu correspond au nom de domaine client générique, contactez Support pour ouvrir un ticket.