So aktivieren Sie die gegenseitige TLS Authentifizierung für Ihr HTTP APIs API In-Gateway

Die gegenseitige TLS Authentifizierung erfordert eine bidirektionale Authentifizierung zwischen dem Client und dem Server. Bei der Gegenseitigkeit müssen Clients X.509-Zertifikate vorlegenTLS, um ihre Identität zu verifizieren, um auf Ihre zugreifen zu können. API Gegenseitig TLS ist eine allgemeine Anforderung für das Internet der Dinge (IoT) und business-to-business Anwendungen.

Sie können Mutual TLS zusammen mit anderen Autorisierungs- und Authentifizierungsvorgängen verwenden, die API Gateway unterstützt. APIGateway leitet die Zertifikate, die Clients zur Verfügung stellen, an Lambda-Autorisierer und an Backend-Integrationen weiter.

Voraussetzungen für Gegenseitigkeit TLS

Um Mutual zu konfigurierenTLS, benötigen Sie:

Benutzerdefinierte Domänennamen

Um Mutual TLS für a zu aktivieren HTTPAPI, müssen Sie einen benutzerdefinierten Domainnamen für Ihren konfigurierenAPI. Sie können Mutual TLS für einen benutzerdefinierten Domainnamen aktivieren und dann den Kunden den benutzerdefinierten Domainnamen zur Verfügung stellen. Um API mithilfe eines benutzerdefinierten Domänennamens, für den Mutual TLS aktiviert ist, auf einen zugreifen zu können, müssen Clients Zertifikate vorlegen, denen Sie bei API Anfragen vertrauen. Sie finden mehr Informationen in Benutzerdefinierte Domainnamen für HTTP APIs in API Gateway.

Verwendung AWS Certificate Manager ausgestellter Zertifikate

Sie können ein öffentlich vertrauenswürdiges Zertifikat direkt von öffentlichen ACM oder selbstsignierten Zertifikaten anfordern oder diese importieren. Um ein Zertifikat einzurichtenACM, gehen Sie zu ACM. Wenn Sie ein Zertifikat importieren möchten, lesen Sie weiter im folgenden Abschnitt.

Verwenden Sie ein importiertes AWS Private Certificate Authority Zertifikat oder ein Zertifikat

Um ein in Mutual importiertes Zertifikat ACM oder ein Zertifikat von AWS Private Certificate Authority Mutual verwenden zu könnenTLS, benötigt API Gateway ein ownershipVerificationCertificate Zertifikat vonACM. Dieses Eigentumszertifikat wird nur verwendet, um zu überprüfen, ob Sie über Berechtigungen zur Verwendung des Domänennamens verfügen. Es wird nicht für den TLS Handshake verwendet. Falls Sie noch keine habenownershipVerificationCertificate, gehen Sie zu, https://console.aws.amazon.com/acm/um eine einzurichten.

Sie müssen dieses Zertifikat für die gesamte Lebensdauer Ihres Domainnamens gültig halten. Wenn ein Zertifikat abläuft und die automatische Verlängerung fehlschlägt, werden alle Updates des Domänennamens gesperrt. Sie müssen die ownershipVerificationCertificateArn mit einem gültigen ownershipVerificationCertificate aktualisieren, bevor Sie weitere Änderungen vornehmen können. Das ownershipVerificationCertificate kann nicht als Serverzertifikat für eine andere gemeinsame TLS Domäne in API Gateway verwendet werden. Wenn ein Zertifikat direkt reimportiert wirdACM, muss der Aussteller derselbe bleiben.

Konfigurieren Ihres Truststore

Truststores sind Textdateien mit einer .pem-Dateierweiterung. Sie sind eine vertrauenswürdige Liste von Zertifikaten von Zertifizierungsstellen. Um Mutual zu verwendenTLS, erstellen Sie einen Truststore mit X.509-Zertifikaten, denen Sie beim Zugriff auf Ihre Zertifikate vertrauen. API

Sie müssen die vollständige Vertrauenskette vom ausstellenden CA-Zertifikat bis zum Stamm-CA-Zertifikat in Ihren Truststore aufnehmen. APIGateway akzeptiert Client-Zertifikate, die von allen in der Vertrauenskette vorhandenen Zertifizierungsstellen ausgestellt wurden. Die Zertifikate können von öffentlichen oder privaten Zertifizierungsstellen stammen. Zertifikate können eine maximale Kettenlänge von vier haben. Sie können auch selbstsignierte Zertifikate bereitstellen. Die folgenden Hash-Algorithmen werden im Truststore unterstützt:

APIGateway validiert eine Reihe von Zertifikatseigenschaften. Sie können Lambda-Autorisierer verwenden, um zusätzliche Prüfungen durchzuführen, wenn ein Client eine aufruftAPI, einschließlich der Überprüfung, ob ein Zertifikat gesperrt wurde. APIGateway validiert die folgenden Eigenschaften:

Hochladen des Vertrauensspeichers in einen Amazon-S3-Bucket in einer einzigen Datei.

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

Der folgende AWS CLI Befehl lädt certificates.pem in Ihren Amazon S3 S3-Bucket hoch.

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

Konfiguration von Mutual TLS für einen benutzerdefinierten Domainnamen

Um Mutual TLS für a zu konfigurieren HTTPAPI, müssen Sie einen regionalen benutzerdefinierten Domainnamen mit einer TLS Mindestversion von 1.2 verwenden. API Weitere Informationen zum Erstellen und Konfigurieren eines benutzerdefinierten Domänennamens finden Sie unter Richten Sie einen regionalen benutzerdefinierten Domainnamen in API Gateway ein.

Nachdem Sie Ihren Truststore auf Amazon S3 hochgeladen haben, können Sie Ihren benutzerdefinierten Domainnamen so konfigurieren, dass er Mutual TLS verwendet. Fügen Sie Folgendes (Schrägstriche enthalten) in ein Terminal ein:

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

Nachdem Sie den Domainnamen erstellt haben, müssen Sie DNS Datensätze und Basispfadzuordnungen für den Betrieb konfigurieren. API Weitere Informationen hierzu finden Sie unter Richten Sie einen regionalen benutzerdefinierten Domainnamen in API Gateway ein.

Rufen Sie an API mithilfe eines benutzerdefinierten Domänennamens auf, für den Gegenseitigkeit erforderlich ist TLS

Um eine API mit TLS aktiviertem Mutual aufzurufen, müssen Clients in der Anfrage ein vertrauenswürdiges Zertifikat angeben. API Wenn ein Client versucht, Ihr Zertifikat aufzurufenAPI, sucht API Gateway in Ihrem Truststore nach dem Aussteller des Client-Zertifikats. Damit API Gateway mit der Anfrage fortfahren kann, müssen sich der Aussteller des Zertifikats und die gesamte Vertrauenskette bis hin zum Root-CA-Zertifikat in Ihrem Truststore befinden.

Mit dem folgenden curl-Beispielbefehl wird eine Anforderung an api.example.com, gesendet, die my-cert.pem in die Anforderung einschließt. my-key.key ist der private Schlüssel für das Zertifikat.

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

Ihr API wird nur aufgerufen, wenn Ihr Truststore dem Zertifikat vertraut. Die folgenden Bedingungen führen dazu, dass API Gateway den TLS Handshake fehlschlägt und die Anfrage mit einem Statuscode ablehnt. 403 Wenn Ihr Zertifikat:

Aktualisieren Ihres Truststore

Um die Zertifikate in Ihrem Truststore zu aktualisieren, laden Sie ein neues Zertifikatspaket in Amazon S3 hoch. Anschließend können Sie Ihren benutzerdefinierten Domänennamen aktualisieren, um das aktualisierte Zertifikat zu verwenden.

Verwenden Sie Amazon-S3-Versioning, um mehrere Versionen Ihres Vertrauensspeichers zu verwalten. Wenn Sie Ihren benutzerdefinierten Domainnamen aktualisieren, um eine neue Truststore-Version zu verwenden, gibt API Gateway Warnungen aus, wenn Zertifikate ungültig sind.

APIGateway gibt nur dann Zertifikatswarnungen aus, wenn Sie Ihren Domainnamen aktualisieren. APIGateway benachrichtigt Sie nicht, wenn ein zuvor hochgeladenes Zertifikat abläuft.

Mit dem folgenden AWS CLI Befehl wird ein benutzerdefinierter Domainname aktualisiert, sodass er eine neue Truststore-Version verwendet.

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'

Deaktivieren Sie gegenseitig TLS

Um Mutual TLS für einen benutzerdefinierten Domainnamen zu deaktivieren, entfernen Sie den Truststore aus Ihrem benutzerdefinierten Domainnamen, wie im folgenden Befehl gezeigt.

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=''

Beheben Sie die Fehlerbehebung bei Mutual TLS für HTTP API

Im Folgenden finden Sie Hinweise zur Behebung von Fehlern und Problemen, die bei der Aktivierung von Mutual auftreten könnenTLS.

Fehlerbehebung bei Zertifikatwarnungen

Bei der Erstellung eines benutzerdefinierten Domainnamens mit Mutual gibt API Gateway Warnungen zurückTLS, wenn Zertifikate im Truststore nicht gültig sind. Dies kann auch auftreten, wenn ein benutzerdefinierter Domänenname aktualisiert wird, um einen neuen Truststore zu verwenden. Die Warnungen geben das Problem mit dem Zertifikat und den Betreff des Zertifikats an, das die Warnung erstellt hat. Mutual TLS ist weiterhin für Sie aktiviertAPI, aber einige Kunden können möglicherweise nicht auf Ihre API zugreifen.

Um aufzudecken, welches Zertifikat die Warnung erzeugt hat, dekodieren Sie die Zertifikate in Ihrem Truststore. Sie können Tools wie openssl zum Dekodieren der Zertifikate und zur Identifizierung ihrer Subjekte verwenden.

Der folgende Befehl zeigt den Inhalt eines Zertifikats einschließlich seines Betreffs an:

openssl x509 -in certificate.crt -text -noout

Aktualisieren oder entfernen Sie die Zertifikate, die Warnungen erstellt haben, und laden Sie dann einen neuen Truststore in Amazon S3 hoch. Nachdem Sie einen neuen Truststore hochgeladen haben, aktualisieren Sie Ihren benutzerdefinierten Domänennamen, um den neuen Truststore zu verwenden.

Problembehandlung bei Domänennamenskonflikten

Der Fehler "The certificate subject <certSubject> conflicts with an existing certificate from a different issuer." bedeutet, dass mehrere Zertifizierungsstellen ein Zertifikat für diese Domäne ausgestellt haben. Für jeden Betreff im Zertifikat kann es in API Gateway für gemeinsame TLS Domänen nur einen Aussteller geben. Sie müssen alle Ihre Zertifikate für dieses Thema über einen einzigen Aussteller abrufen. Wenn das Problem mit einem Zertifikat besteht, das Sie nicht kontrollieren können, Sie jedoch den Besitz des Domänennamens nachweisen können, kontaktieren Sie AWS Support, um ein Ticket zu eröffnen.

Fehlerbehebung bei Statusmeldungen für Domänennamen

PENDING_CERTIFICATE_REIMPORT: Das bedeutet, dass Sie ein Zertifikat erneut importiert haben ACM und die Überprüfung fehlgeschlagen ist, weil das neue Zertifikat einen SAN (alternativen Antragstellernamen) hat, der nicht durch den ownershipVerificationCertificate oder der Betreff oder SANs im Zertifikat nicht den Domainnamen abgedeckt ist. Möglicherweise ist etwas falsch konfiguriert oder ein ungültiges Zertifikat wurde importiert. Sie müssen ein gültiges Zertifikat erneut importieren in. ACM Weitere Informationen zur Validierung finden Sie unter Validierung des Domänenbesitzes.

PENDING_OWNERSHIP_VERIFICATION: Das bedeutet, dass Ihr zuvor verifiziertes Zertifikat abgelaufen ist und es nicht automatisch verlängert werden ACM konnte. Sie müssen das Zertifikat erneuern oder ein neues Zertifikat anfordern. Weitere Informationen zur Verlängerung von Zertifikaten finden Sie im Leitfaden zur Fehlerbehebung bei ACM der Verlängerung verwalteter Zertifikate.