Verwenden Sie Ihr eigenes ACM-Zertifikat für gegenseitiges Backend-TLS in API Gateway

Sie können API Gateway so konfigurieren, dass Back-End-Diensten Ihr eigenes CA-signed Zertifikat präsentiert wird. Importieren Sie Ihr Zertifikat in AWS Certificate Manager (ACM) oder stellen Sie eines aus. AWS Private Certificate Authority Verknüpfen Sie dann den ARN des ACM-Zertifikats mit Ihrer API-Stufe.

Voraussetzungen

Bevor Sie ein ACM-Client-Zertifikat konfigurieren, müssen Sie über Folgendes verfügen:

• AWS Certificate Manager Zugriff in derselben Region wie Ihre API.

• IAM-Berechtigungen: acm:ImportCertificate und acm:DescribeCertificate (für Option A-Import) oder acm:RequestCertificate (für Option B), oder acm-pca:IssueCertificateacm-pca:GetCertificate, und acm:ImportCertificate (für Option C).

• Eine REST-API, die in einer Phase bereitgestellt wird.

Schritt 1: Importieren Sie ein Zertifikat oder stellen Sie eines aus über AWS Private Certificate Authority

Sie können entweder ein Zertifikat aus Ihrer vorhandenen PKI importieren oder ein neues Zertifikat über AWS Private Certificate Authority ausstellen. Beide Pfade erzeugen einen ACM-Zertifikat-ARN, den Sie im folgenden Schritt verwenden.

Anmerkung

Öffentliche ACM-Zertifikate werden für die Backend-Client-Authentifizierung nicht unterstützt. Stellt ab dem 11. Juni 2025 AWS Certificate Manager keine öffentlichen Zertifikate mehr mit der clientAuth erweiterten Schlüsselnutzung (EKU) aus. Für diese Funktion ist diese EKU erforderlich. Verwenden Sie daher ein Zertifikat, das Sie in ACM importieren, oder eines, das über ACM ausgestellt wurde. AWS Private Certificate Authority

Anmerkung

Erstellen Sie das ACM-Zertifikat in derselben AWS Region wie die REST-API, die es verwenden wird. ACM-Zertifikate sind regionale Ressourcen, daher muss das Zertifikat in der Region Ihrer API vorhanden sein.

Option A: Import aus Ihrer vorhandenen PKI

Führen Sie den folgenden Befehl aus, um ein Client-Zertifikat und seinen privaten Schlüssel in ACM zu importieren. Weitere Informationen finden Sie unter Importieren von Zertifikaten im AWS Certificate Manager -Benutzerhandbuch.

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

Der Befehl gibt die ARN des ACM-Zertifikats zurück. Notieren Sie sich diesen Wert für den folgenden Schritt.

Option B: Fordern Sie ein Zertifikat an AWS Private Certificate Authority (ACM-managed)

Führen Sie den folgenden Befehl aus, um ein privates Zertifikat anzufordern, das von ACM verwaltet wird und das automatisch erneuert werden kann. Weitere Informationen finden Sie im AWS Certificate Manager Benutzerhandbuch unter Anfordern eines privaten Zertifikats.

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

Der Befehl gibt die ARN des ACM-Zertifikats zurück. Notieren Sie sich diesen Wert für den folgenden Schritt.

Option C: Ausgabe bis AWS Private Certificate Authority und in ACM importieren

Wenn Sie direkte Kontrolle über die Zertifikatsparameter benötigen (z. B. benutzerdefinierte Erweiterungen oder Signaturalgorithmen), können Sie ein Zertifikat über ACM ausstellen AWS Private Certificate Authority und es dann in ACM importieren. Auf diese Weise importierte Zertifikate werden von ACM nicht automatisch erneuert. Stellen Sie sicher, dass das Zertifikat die Zertifikatsanforderungen erfüllt. Weitere Informationen zur Ausstellung von privaten Zertifikaten finden Sie im AWS Private Certificate Authority Benutzerhandbuch unter Ausstellen eines privaten Endentitätszertifikats.

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

Rufen Sie das Zertifikat ab und importieren Sie es

Der issue-certificate Befehl gibt eine AWS Private Certificate Authority Zertifikats-ARN zurück, keine ACM-ARN. Um dieses Zertifikat mit API Gateway zu verwenden, rufen Sie es mithilfe von API Gateway ab aws acm-pca get-certificate und importieren Sie es dann in ACM. aws acm import-certificate Der Import erzeugt den ARN des ACM-Zertifikats, den Sie im folgenden Schritt verwenden. Stellen Sie bei der Ausführung --region die Region Ihrer API einaws acm import-certificate, damit das ACM-Zertifikat dort erstellt wird.

Schritt 2: Konfigurieren Sie eine API-Stufe für die Verwendung des ACM-Zertifikats

Nachdem Sie über einen ARN für ein ACM-Zertifikat verfügen, richten Sie Ihre API-Stufe ein, um das Zertifikat Ihrem Backend zu präsentieren.

So konfigurieren Sie eine Phase (Konsole)

1. Öffnen Sie die API Gateway-Konsole unter https://console.aws.amazon.com/apigateway.

2. Wählen Sie Ihre REST-API.

3. Wählen Sie Stages.

4. Wählen Sie im Abschnitt Stage details (Stufendetails) die Option Edit (Bearbeiten) aus.

5. Wählen Sie für das Client-Zertifikat Ihr ACM-Zertifikat aus der Dropdownliste aus.

6. Wählen Sie Änderungen speichern aus.

Um eine Stufe zu konfigurieren (AWS CLI)

Führen Sie den folgenden Befehl aus:

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

Anmerkung

API Gateway verwendet dasselbe clientCertificateId Feld sowohl für ACM- als auch für Gateway-generated API-Zertifikate. Wenn Sie einen ARN für ein ACM-Zertifikat angeben, erkennt API Gateway das Format automatisch und verwendet den ACM-managed Workflow.

Schritt 3: Überprüfen Sie die Konfiguration

Gehen Sie wie folgt vor, um zu überprüfen, ob API Gateway das Zertifikat an Ihr Backend sendet:

Das Backend muss ein Client-Zertifikat anfordern

Ihr Backend muss so konfiguriert sein, dass es während des TLS-Handshakes ein Client-Zertifikat anfordert. Wenn das Backend keines anfordert, präsentiert API Gateway das Zertifikat nicht.

1. Rufen Sie Ihren API-Endpunkt auf.

2. Vergewissern Sie sich, dass Ihr Backend das Client-Zertifikat während des TLS-Handshakes erhält.

3. Stellen Sie sicher, dass Ihr Backend das Zertifikat akzeptiert und eine erfolgreiche Antwort zurückgibt.

Wenn das Backend das Zertifikat ablehnt, stellen Sie sicher, dass die Zertifikatskette anhand des Trust Stores des Backends validiert werden kann.

Zertifikatanforderungen

Das Leaf-Zertifikat, das Sie konfigurieren, muss die folgenden Anforderungen erfüllen.

Anforderungen an das ACM-Client-Zertifikat

Anforderung	Description
Maximale Kettenlänge	5 Zertifikate
Gültigkeit	Das Zertifikat darf nicht abgelaufen oder noch gültig sein, wenn Sie es konfigurieren
Region	Das ACM-Zertifikat muss sich in derselben Region wie die API befinden
Account	Das ACM-Zertifikat muss sich im selben Konto wie die API befinden
Erweiterte Schlüsselnutzung (EKU)	Falls vorhanden, muss Folgendes enthalten: clientAuth Falls nicht vorhanden, wird das Zertifikat akzeptiert.
Verwendung von Schlüsseln (KU)	Falls vorhanden, muss digitalSignature oder enthaltenkeyAgreement. Falls nicht vorhanden, wird das Zertifikat akzeptiert.
Schlüsselalgorithmus	Muss einer der folgenden Werte sein: RSA 2048, RSA 3072, RSA 4096, ECDSA (ec_Prime256v1), ECDSA (ec_SECP384R1) oder ECDSA P-256 (ec_SECP521R1) P-384 P-521
Status des ACM-Zertifikats	Muss ISSUED sein.

Anmerkung

API Gateway validiert die Vertrauenskette zwischen den Leaf- und Zwischenzertifikaten nicht. API Gateway überprüft auch nicht die Absicht des Zertifikats oder grundlegende Einschränkungen (wie z. B.CA:TRUE) für Zwischenzertifikate. Ihr Backend führt diese Validierungen während des TLS-Handshakes durch.

Erneuerung und Weitergabe des Zertifikats

Wenn sich ein Zertifikat in ACM ändert, erkennt API Gateway die Aktualisierung und verteilt das neue Zertifikat automatisch. Sie müssen Ihre Stagingphase nicht erneut bereitstellen, und Ihre API hat während der Rotation keine Ausfallzeiten.

Die Zertifikatsweitergabe ist letztendlich konsistent. Während des Updates erhält Ihr Backend möglicherweise entweder das alte oder das neue Zertifikat, bis die Propagierung abgeschlossen ist.

Wie das Zertifikat erneuert wird, hängt davon ab, wie es ausgestellt wurde:

• Mit AWS Private Certificate Authority (ACM-managed) ausgestellte Zertifikate (Option B) — ACM erneuert diese Zertifikate automatisch. API Gateway erkennt die Verlängerung und aktualisiert sie automatisch.

• Von AWS Private Certificate Authority und importierte Zertifikate (Option C) — ACM erneuert importierte Zertifikate nicht automatisch. Sie müssen das erneuerte Zertifikat erneut importieren. Nachdem Sie das Zertifikat erneut importiert haben, erkennt API Gateway die Änderung und aktualisiert sie automatisch.

• Importierte Zertifikate aus Ihrer PKI (Option A) — Sie müssen das erneuerte Zertifikat erneut in ACM importieren. Nachdem Sie das Zertifikat erneut importiert haben, erkennt API Gateway die Änderung und aktualisiert sie automatisch.

ACM sendet Benachrichtigungen über den Ablauf des Zertifikats über Amazon. EventBridge Sie können diese Benachrichtigungen verwenden, um Alarme einzurichten, bevor ein Zertifikat abläuft.

Verhalten und Einschränkungen des ACM-Zertifikats

Das konfigurierte Zertifikat anzeigen

ACM-Zertifikate erscheinen nicht in den GetClientCertificate oder GetClientCertificates API-Antworten. Um die auf einer Stufe konfigurierte ARN des ACM-Zertifikats anzuzeigen, verwenden Sie. GetStage Verwenden Sie die ACM-APIs DescribeCertificate und, um die Zertifikatsdetails anzuzeigen. GetCertificate

Stufenübergreifende Wiederverwendung

Sie können dasselbe ACM-Zertifikat an mehrere Stufen anhängen. Jede Phase referenziert das Zertifikat unabhängig anhand ihrer ARN.

Client-Zertifikat-APIs gelten nicht für ACM-Zertifikate

ACM-Zertifikate sind keine Gateway-managed API-Ressourcen. Die DeleteClientCertificate APIsGetClientCertificate,UpdateClientCertificate, und geben einen ARN zurück, NotFoundException wenn sie mit einem ACM-Zertifikat aufgerufen werden. Verwenden Sie ACM-APIs, um den Lebenszyklus des Zertifikats zu verwalten.

Automatische Bereinigung der Zertifikatszuordnungen

Wenn Sie ein ACM-Zertifikat aus einem Stagingbereich entfernen, einen Stagingbereich so aktualisieren, dass er ein anderes Zertifikat verwendet, oder einen Stagingbereich oder eine REST-API löschen, bereinigt API Gateway die Zertifikatszuordnung automatisch. Es sind keine manuellen Maßnahmen erforderlich.

Löschen des ACM-Zertifikats

ACM erlaubt es Ihnen nicht, ein Zertifikat zu löschen, solange API Gateway eine aktive Verknüpfung damit hat. Um das Zertifikat aus ACM zu löschen, entfernen Sie es zunächst aus allen Stufen, die darauf verweisen.