So aktivieren Sie die gegenseitige TLS Authentifizierung für Ihr REST 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 bereitstellen, an Lambda-Autorisierer und an Backend-Integrationen weiter.

Wichtig

Standardmäßig können Clients Ihre aufrufen, indem sie den Endpunkt verwenden, den API execute-api Gateway für Sie generiert. API API Um sicherzustellen, dass Clients API nur über einen benutzerdefinierten Domainnamen mit Mutual auf Ihren zugreifen könnenTLS, deaktivieren Sie den execute-api Standardendpunkt. Weitere Informationen hierzu finden Sie unter Deaktivieren Sie den Standardendpunkt für REST-APIs.

Voraussetzungen für Gegenseitigkeit TLS

Um Mutual zu konfigurierenTLS, benötigen Sie:

• Ein regionaler benutzerdefinierter Domainname

• AWS Certificate Manager Für Ihren benutzerdefinierten Domainnamen ist mindestens ein Zertifikat konfiguriert

• Ein in Amazon S3 konfigurierter und hochgeladener Truststore

Benutzerdefinierte Domänennamen

Um Mutual TLS für a zu aktivieren RESTAPI, 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 Benutzerdefinierter Domainname für REST 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 Algorithmen werden im Truststore unterstützt:

• SHA-256 oder stärker

• RSA-2048 oder stärker

• ECDSA-256 oder -384 ECDSA

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:

Validierung	Beschreibung
X.509-Syntax	Das Zertifikat muss die X.509-Syntaxanforderungen erfüllen.
Integrität	Der Inhalt des Zertifikats darf sich nicht von dem unterscheiden, was von der Zertifizierungsstelle des Truststore signiert wurde.
Gültigkeit	Die Gültigkeitsdauer des Zertifikats muss aktuell sein.
Namensverkettung/Schlüsselverkettung	Die Verkettung der Namen und Antragssteller von Zertifikaten darf nicht unterbrochen sein. Zertifikate können eine maximale Kettenlänge von vier haben.

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

Im Folgenden finden Sie ein Beispiel dafür, wie eine .pem-Datei aussehen könnte.

Beispiel certificates.pem

-----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 RESTAPI, müssen Sie einen regionalen benutzerdefinierten Domainnamen mit einer TLS_1_2 Sicherheitsrichtlinie verwenden. API Weitere Informationen zur Auswahl einer Sicherheitsrichtlinie finden Sie unterWählen Sie eine Sicherheitsrichtlinie für Ihre REST API benutzerdefinierte Domain in API Gateway.

Anmerkung

Gegenseitig wird privat TLS nicht unterstütztAPIs.

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

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:

• nicht vertrauenswürdig ist

• abgelaufen ist

• keinen unterstützten Algorithmus verwendet

Anmerkung

APIGateway überprüft nicht, ob ein Zertifikat gesperrt wurde.

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 apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreVersion',value='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 apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

Trouble mutual TLS für dein REST API

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

Fehlerbehebung bei Zertifikatwarnungen

Beim Erstellen 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.

Fehlerbehebung bei falsch zurückgegebenen Zertifikaten

Bei der Migration eines dedizierten Zertifikats von einem vollqualifizierten Domainnamen (FQDN) zu einem Platzhalter-Kundendomänennamen gibt API Gateway möglicherweise das Zertifikat für den FQDN statt für den Platzhalterdomänennamen zurück.

Der folgende Befehl zeigt an, welches Zertifikat von Gateway zurückgegeben wird: API

openssl s_client -connect hostname:port

Wenn das resultierende Zertifikat für den bestimmt istFQDN, wenden Sie sich an, AWS Support um ein Ticket zu öffnen.