View a markdown version of this page

Utilisez votre propre certificat ACM pour le TLS mutuel du backend dans API Gateway - Amazon API Gateway
Conditions préalablesÉtape 1 : Importez un certificat ou émettez-en un via Autorité de certification privée AWSÉtape 2 : Configuration d'un stage d'API pour utiliser le certificat ACMÉtape 3 : Vérifiez la configurationExigences du certificatRenouvellement et propagation des certificatsComportement et limites des certificats ACM

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisez votre propre certificat ACM pour le TLS mutuel du backend dans API Gateway

Vous pouvez configurer API Gateway pour présenter votre propre CA-signed certificat aux services principaux. Importez votre certificat dans AWS Certificate Manager (ACM) ou émettez-en un via Autorité de certification privée AWS. Liez ensuite l'ARN du certificat ACM à votre étape d'API.

Conditions préalables

Avant de configurer un certificat client ACM, vous devez disposer des éléments suivants :

  • AWS Certificate Manager accès dans la même région que votre API.

  • Autorisations IAM : acm:ImportCertificate et acm:DescribeCertificate (pour l'importation de l'option A), ou acm:RequestCertificate (pour l'option B), ou acm-pca:IssueCertificateacm-pca:GetCertificate, et acm:ImportCertificate (pour l'option C).

  • Une API REST déployée sur une scène.

Étape 1 : Importez un certificat ou émettez-en un via Autorité de certification privée AWS

Vous pouvez soit importer un certificat à partir de votre PKI existante, soit émettre un nouveau certificat via Autorité de certification privée AWS. Les deux chemins produisent un ARN de certificat ACM que vous utiliserez à l'étape suivante.

Note

Les certificats publics ACM ne sont pas pris en charge pour l'authentification du client principal. À compter du 11 juin 2025, AWS Certificate Manager n'émettra plus de certificats publics avec l'utilisation clientAuth étendue des clés (EKU). Cette fonctionnalité nécessite cet EKU. Utilisez donc un certificat que vous importez dans ACM ou un certificat émis via. Autorité de certification privée AWS

Note

Créez le certificat ACM dans la même AWS région que l'API REST qui l'utilisera. Les certificats ACM sont des ressources régionales. Le certificat doit donc exister dans la région de votre API.

Option A : Importer depuis votre PKI existante

Pour importer un certificat client et sa clé privée dans ACM, exécutez la commande suivante. Pour plus d'informations, consultez la section Importation de certificats dans le AWS Certificate Manager Guide de l'utilisateur.

aws acm import-certificate \
  --certificate fileb://client-cert.pem \
  --private-key fileb://private-key.pem \
  --certificate-chain fileb://ca-chain.pem \
  --region region

La commande renvoie l'ARN du certificat ACM. Enregistrez cette valeur pour l'étape suivante.

Option B : demandez un certificat via Autorité de certification privée AWS (ACM-managed)

Pour demander un certificat privé qu'ACM gère et peut renouveler automatiquement, exécutez la commande suivante. Pour plus d'informations, consultez la section Demande de certificat privé dans le Guide de AWS Certificate Manager l'utilisateur.

aws acm request-certificate \
  --domain-name www.example.com \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --region region

La commande renvoie l'ARN du certificat ACM. Enregistrez cette valeur pour l'étape suivante.

Option C : Émettre par Autorité de certification privée AWS et importez dans ACM

Si vous avez besoin de contrôler directement les paramètres du certificat (tels que des extensions personnalisées ou des algorithmes de signature), vous pouvez émettre un certificat via ACM, Autorité de certification privée AWS puis l'importer dans ACM. Les certificats importés de cette manière ne sont pas renouvelés automatiquement par ACM. Assurez-vous que le certificat répond aux exigences du certificat. Pour plus d'informations sur l'émission de certificats privés, consultez la section Émission d'un certificat d'entité finale privée dans le Guide de l'Autorité de certification privée AWS utilisateur.

aws acm-pca issue-certificate \
  --certificate-authority-arn arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/12345678-1234-1234-1234-123456789012 \
  --csr fileb://csr.pem \
  --signing-algorithm SHA256WITHRSA \
  --validity Value=365,Type=DAYS
Récupérez et importez le certificat

La issue-certificate commande renvoie un ARN de Autorité de certification privée AWS certificat, et non un ARN ACM. Pour utiliser ce certificat avec API Gateway, récupérez-le à l'aide de, aws acm-pca get-certificate puis importez-le dans ACM à l'aide aws acm import-certificate de. L'importation produit l'ARN du certificat ACM que vous utiliserez à l'étape suivante. Lorsque vous exécutezaws acm import-certificate, définissez --region la région de votre API pour que le certificat ACM y soit créé.

Étape 2 : Configuration d'un stage d'API pour utiliser le certificat ACM

Une fois que vous avez un ARN de certificat ACM, configurez votre étape d'API pour présenter le certificat à votre backend.

Pour configurer une scène (console)

  1. Ouvrez la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

  2. Choisissez votre API REST.

  3. Choisissez Stages (Étapes).

  4. Dans la section Détails de l’étape, choisissez Modifier.

  5. Pour le certificat client, sélectionnez votre certificat ACM dans la liste déroulante.

  6. Sélectionnez Enregistrer les modifications.

Pour configurer une étape (AWS CLI)

Exécutez la commande suivante :

aws apigateway update-stage \
  --rest-api-id abc123 \
  --stage-name prod \
  --patch-operations op='replace',path=/clientCertificateId,value=arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
Note

API Gateway utilise le même clientCertificateId champ pour les Gateway-generated certificats ACM et API. Lorsque vous fournissez un ARN de certificat ACM, API Gateway détecte automatiquement le format et utilise le ACM-managed flux de travail.

Étape 3 : Vérifiez la configuration

Pour vérifier qu'API Gateway envoie le certificat à votre backend, procédez comme suit :

Le backend doit demander un certificat client

Votre backend doit être configuré pour demander un certificat client lors de la prise de contact TLS. Si le backend n'en demande pas, API Gateway ne présente pas le certificat.

  1. Invoquez le point de terminaison de votre API.

  2. Vérifiez que votre backend obtient le certificat client lors de la prise de contact TLS.

  3. Vérifiez que votre backend accepte le certificat et renvoie une réponse correcte.

Si le backend rejette le certificat, vérifiez que la chaîne de certificats peut être validée par rapport au trust store du backend.

Exigences du certificat

Le certificat Leaf que vous configurez doit répondre aux exigences suivantes.

Exigences relatives aux certificats clients ACM
Exigence Description
Longueur maximale de la chaîne 5 certificats
Validité Le certificat ne doit pas avoir expiré ou être encore valide lorsque vous le configurez
Région Le certificat ACM doit se trouver dans la même région que l'API
Compte Le certificat ACM doit être associé au même compte que l'API
Utilisation étendue des clés (EKU) Le cas échéant, doit inclureclientAuth. En cas d'absence, le certificat est accepté.
Utilisation des clés (KU) Le cas échéant, doit inclure digitalSignature oukeyAgreement. En cas d'absence, le certificat est accepté.
Algorithme clé Doit être l'un des suivants : RSA 2048, RSA 3072, RSA 4096, ECDSA (EC_Prime256v1), ECDSA (EC_SecP384R1) ou ECDSA P-256 (EC_SecP521R1) P-384 P-521
État du certificat ACM Doit être ISSUED
Note

API Gateway ne valide pas la chaîne de confiance entre le certificat initial et le certificat intermédiaire. API Gateway ne valide pas non plus l'intention du certificat ni les contraintes de base (telles queCA:TRUE) sur les certificats intermédiaires. Votre backend effectue ces validations lors de la prise de contact TLS.

Renouvellement et propagation des certificats

Lorsqu'un certificat est modifié dans ACM, API Gateway détecte la mise à jour et propage automatiquement le nouveau certificat. Vous n'avez pas besoin de redéployer votre stage et votre API ne subit aucune interruption pendant la rotation.

La propagation des certificats est finalement cohérente. Pendant la mise à jour, votre backend peut recevoir l'ancien ou le nouveau certificat jusqu'à la fin de la propagation.

Le mode de renouvellement du certificat dépend de la manière dont il a été délivré :

  • Certificats émis via Autorité de certification privée AWS (ACM-managed) (Option B) — ACM renouvelle automatiquement ces certificats. API Gateway détecte le renouvellement et se met à jour automatiquement.

  • Certificats émis Autorité de certification privée AWS et importés (option C) — ACM ne renouvelle pas automatiquement les certificats importés. Vous devez réimporter le certificat renouvelé. Une fois que vous avez réimporté le certificat, API Gateway détecte le changement et le met à jour automatiquement.

  • Certificats importés depuis votre PKI (option A) — Vous devez réimporter le certificat renouvelé dans ACM. Une fois que vous avez réimporté le certificat, API Gateway détecte le changement et le met à jour automatiquement.

ACM envoie des notifications d'expiration des certificats via Amazon EventBridge. Vous pouvez utiliser ces notifications pour configurer des alarmes avant l'expiration d'un certificat.

Comportement et limites des certificats ACM

Affichage du certificat configuré

Les certificats ACM n'apparaissent pas dans les réponses GetClientCertificate ni dans les réponses de GetClientCertificates l'API. Pour afficher l'ARN du certificat ACM configuré sur une scène, utilisez GetStage. Pour afficher les détails du certificat, utilisez les API ACM DescribeCertificate et GetCertificate.

Réutilisation à travers les étapes

Vous pouvez associer le même certificat ACM à plusieurs étapes. Chaque étape référence indépendamment le certificat par son ARN.

Les API de certificats clients ne s'appliquent pas aux certificats ACM

Les certificats ACM ne sont pas des Gateway-managed ressources d'API. Les DeleteClientCertificate APIGetClientCertificate,UpdateClientCertificate, et renvoient une valeur NotFoundException lorsqu'elles sont appelées avec un ARN de certificat ACM. Utilisez les API ACM pour gérer le cycle de vie des certificats.

Nettoyage automatique des associations de certificats

Lorsque vous supprimez un certificat ACM d'un stage, que vous mettez à jour un stage pour utiliser un autre certificat, ou que vous supprimez un stage ou une API REST, API Gateway nettoie automatiquement l'association de certificats. Aucune action manuelle n'est requise.

Supprimer le certificat ACM

ACM ne vous permet pas de supprimer un certificat alors qu'API Gateway y est activement associé. Pour supprimer le certificat d'ACM, supprimez-le d'abord de toutes les étapes qui le référencent.