Comment activer l'TLSauthentification mutuelle pour votre compte REST APIs in API Gateway

TLSL'authentification mutuelle nécessite une authentification bidirectionnelle entre le client et le serveur. Avec MutualTLS, les clients doivent présenter des certificats X.509 pour vérifier leur identité afin d'accéder à votreAPI. TLSLa mutualité est une exigence courante pour l'Internet des objets (IoT) et business-to-business les applications.

Vous pouvez utiliser les opérations mutuelles TLS ainsi que les autres opérations d'autorisation et d'authentification prises en charge par API Gateway. APIGateway transmet les certificats fournis par les clients aux autorisateurs Lambda et aux intégrations de backend.

Important

Par défaut, les clients peuvent vous appeler API en utilisant le execute-api point de terminaison généré par API Gateway pour vousAPI. Pour vous assurer que les clients ne peuvent accéder au vôtre API qu'en utilisant un nom de domaine personnalisé avec mutuelTLS, désactivez le point de execute-api terminaison par défaut. Pour en savoir plus, consultez Désactiver le point de terminaison par défaut pour les API REST.

Conditions préalables à la mutuelle TLS

Pour configurer Mutual, TLS vous devez :

• Un nom de domaine personnalisé régional

• Au moins un certificat configuré AWS Certificate Manager pour votre nom de domaine personnalisé

• Un magasin de confiance configuré et chargé vers Amazon S3

Noms de domaine personnalisés

Pour activer la mutuelle TLS pour un RESTAPI, vous devez configurer un nom de domaine personnalisé pour votreAPI. Vous pouvez activer la mutuelle TLS pour un nom de domaine personnalisé, puis fournir le nom de domaine personnalisé aux clients. Pour accéder à un en API utilisant un nom de domaine personnalisé TLS activé mutuellement, les clients doivent présenter des certificats auxquels vous faites confiance lors des API demandes. Vous trouverez plus d'informations dans Nom de domaine personnalisé pour REST APIs in API Gateway.

Utilisation de certificats AWS Certificate Manager émis

Vous pouvez demander un certificat approuvé par le public directement auprès de ACM ou importer des certificats publics ou auto-signés. Pour configurer un certificat dansACM, rendez-vous sur 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é ACM ou un certificat provenant de AWS Private Certificate Authority MutualTLS, API Gateway a besoin d'un certificat ownershipVerificationCertificate émis parACM. 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 TLS poignée de main. 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 TLS domaine commun dans API Gateway. Si un certificat est directement réimporté dansACM, l'émetteur 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 MutualTLS, créez un truststore 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. APIGateway 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 truststore :

• SHA-256 ou plus

• RSA-2048 ou plus

• ECDSA-256 ou ECDSA -384

APIGateway valide un certain nombre de propriétés de certificat. Vous pouvez utiliser les autorisateurs Lambda pour effectuer des contrôles supplémentaires lorsqu'un client invoque unAPI, notamment pour vérifier si un certificat a été révoqué. APIGateway valide les propriétés suivantes :

Validation	Description
Syntaxe X.509	Le certificat doit répondre aux exigences de syntaxe X.509.
Intégrité	Le contenu du certificat ne doit pas avoir été modifié par rapport à celui signé par l'autorité de certification à partir du magasin de confiance.
Validité	La période de validité du certificat doit en cours.
Chaînage de noms / chaînage de clés	Les noms et les objets des certificats doivent former une chaîne ininterrompue. Les certificats peuvent avoir une longueur de chaîne maximale de quatre.

Chargez le magasin de confiance dans un fichier unique d'un compartiment Amazon S3.

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

Exemple certificates.pem

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

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

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

Configuration de la mutuelle TLS pour un nom de domaine personnalisé

Pour configurer la mutuelle TLS pour un RESTAPI, vous devez utiliser un nom de domaine personnalisé régional pour votreAPI, avec une politique TLS_1_2 de sécurité. Pour plus d'informations sur le choix d'une politique de sécurité, consultezChoisissez une politique de sécurité pour votre domaine REST API personnalisé dans API Gateway.

Note

Mutual TLS n'est pas pris en charge pour le mode privéAPIs.

Après avoir chargé votre truststore sur Amazon S3, vous pouvez configurer votre nom de domaine personnalisé pour qu'il utilise MutualTLS. Collez le texte suivant (barres obliques incluses) dans un terminal :

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 devez configurer les DNS enregistrements et les mappages de chemins de base pour les opérations. API Pour en savoir plus, consultez Configurer un nom de domaine personnalisé régional dans API Gateway.

Invoquez un API en utilisant un nom de domaine personnalisé qui nécessite une mutuelle TLS

Pour appeler un API avec Mutual TLS Enabled, les clients doivent présenter un certificat sécurisé dans la API demande. Lorsqu'un client tente d'invoquer votre certificatAPI, API Gateway recherche l'émetteur du certificat client dans votre truststore. Pour que API Gateway puisse traiter la demande, l'émetteur du certificat et l'ensemble de la chaîne de confiance jusqu'au certificat de l'autorité de certification racine doivent se trouver dans votre truststore.

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 n'APIest invoqué que si votre truststore fait confiance au certificat. Dans les conditions suivantes, API Gateway échouera à établir la TLS poignée de main et rejettera la demande avec un code d'403état. Si votre certificat :

• n'est pas approuvé

• a expiré

• n'utilise pas d'algorithme pris en charge

Note

APIGateway ne vérifie pas si un certificat a été révoqué.

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é pour utiliser une nouvelle version de Truststore, API Gateway renvoie des avertissements si les certificats ne sont pas valides.

APIGateway émet des avertissements relatifs aux certificats uniquement lorsque vous mettez à jour votre nom de domaine. APIGateway ne vous avertit pas si un certificat précédemment téléchargé expire.

La AWS CLI commande 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 la mutuelle TLS

Pour désactiver la mutuelle TLS pour un nom de domaine personnalisé, supprimez le truststore de votre nom de domaine personnalisé, comme indiqué dans la commande suivante.

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

Résoudre les problèmes mutuels TLS pour votre REST API

Vous trouverez ci-dessous des conseils de résolution des erreurs et des problèmes que vous pourriez rencontrer lors de l'activation de MutualTLS.

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

Lors de la création d'un nom de domaine personnalisé avec MutualTLS, API Gateway renvoie des avertissements si les certificats du truststore 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. Mutual TLS est toujours activé pour vousAPI, mais certains clients ne pourront peut-être pas y accéderAPI.

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 émetteur dans API Gateway pour les TLS domaines communs. 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 AWS 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 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 qui, SANs dans 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 n'ACMa pas pu être renouvelé automatiquement. Vous devrez renouveler le certificat ou demander un nouveau certificat. Vous trouverez de plus amples informations sur le renouvellement des certificats dans le guide ACMde résolution des problèmes liés au renouvellement géré des certificats.

Résoudre les problèmes liés au certificat renvoyé erroné

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

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

openssl s_client -connect hostname:port

Si le certificat obtenu est pour leFQDN, contactez AWS Support pour ouvrir un ticket.