Configuration de l'authentification TLS mutuelle pour une API HTTP

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. L'authentification TLS mutuelle est une exigence courante pour l'Internet des objets (IOT) et les applications inter-entreprises.

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.

Important

Par défaut, les clients peuvent appeler votre API en utilisant le point de terminaison execute-api généré par API Gateway pour votre API. Pour vous assurer que les clients peuvent accéder à votre API en utilisant uniquement un nom de domaine personnalisé avec authentification TLS mutuelle, désactivez le point de terminaison par défaut execute-api. Pour en savoir plus, veuillez consulter la section Désactivation du point de terminaison par défaut pour une API HTTP.

Conditions préalables pour l'authentification TLS mutuelle

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

• Un nom de domaine personnalisé

• Au moins un certificat configuré dans 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 l'authentification TLS mutuelle pour une API HTTP, 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 Configuration des noms de domaine personnalisés pour les API HTTP.

Utiliser des AWS Certificate Manager certificats é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.

Utiliser un certificat importé ou un certificat AWS Private Certificate Authority

Pour utiliser un certificat importé dans ACM ou un certificat depuis AWS Private Certificate Authority avec une authentification TLS mutuelle, API Gateway a besoin d'un 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'avez pas encore de ownershipVerificationCertificate, accédez àhttps://console.aws.amazon.com/acm/ pour en configurer 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 de hachage suivants sont pris en charge dans le magasin de confiance :

• SHA-256 ou plus

• RSA-2048 ou plus

• ECDSA-256 ou plus

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 :

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.

Exemple certificates.pem

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

La commande AWS CLI CLI suivante charge certificates.pem vers 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 HTTP, vous devez utiliser un nom de domaine personnalisé régional pour votre API, avec une version minimale TLS 1.2. Pour de plus amples informations sur la création et la configuration d'un nom de domaine personnalisé, veuillez consulter Configuration d'un nom de domaine personnalisé régional dans API Gateway.

Note

L'authentification TLS mutuelle n'est pas prise en charge pour les API privées.

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. Collez le texte suivant (barres obliques incluses) dans un terminal :

aws apigatewayv2 create-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --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, veuillez consulter 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 403 code d'état. Si votre certificat :

• n'est pas approuvé

• a expiré

• n'utilise pas d'algorithme pris en charge

Note

L'API Gateway 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é 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 commande AWS CLI suivante met à jour un nom de domaine personnalisé de manière à utiliser la nouvelle version d'un magasin de confiance.

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreVersion='abcdef123'

Désactiver l'authentification TLS mutuelle

Pour désactiver l'authentification TLS mutuelle pour un nom de domaine personnalisé, supprimez le magasin de confiance de votre nom de domaine personnalisé, comme indiqué dans la commande suivante.

aws apigatewayv2 update-domain-name \
    --domain-name api.example.com \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678 \
    --mutual-tls-authentication TruststoreUri=''

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 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 dans ACM qui a provoqué l'échec de la validation, car le nouveau certificat a un SAN (nom alternatif de l'objet) qui n'est pas couvert par le ownershipVerificationCertificate ou par l'objet ou que les SAN du certificat ne couvrent 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. Pour en savoir plus sur le renouvellement du certificat, vous trouverez des informations supplémentaires dans le guide : Résolution des problèmes liés au renouvellement des certificats gérés par ACM.