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

Die gegenseitige TLS-Authentifizierung erfordert eine bidirektionale Authentifizierung zwischen dem Client und dem Server. Bei gegenseitiger TLS müssen Clients X.509-Zertifikate zur Prüfung ihrer Identität präsentieren, um auf Ihre API zuzugreifen. Gegenseitiges TLS ist eine allgemeine Anforderung für das Internet der Dinge (IoT) und business-to-business Anwendungen.

Sie können gegenseitiges TLS zusammen mit anderen Autorisierungs- und Authentifizierungsvorgängen verwenden, die API Gateway unterstützt. API Gateway leitet die von Kunden bereitgestellten Zertifikate an Lambda-Genehmiger und an Backend-Integrationen weiter.

Voraussetzungen für gegenseitige TLS

Um gegenseitige TLS zu konfigurieren, benötigen Sie:

Benutzerdefinierte Domainnamen

Um die gegenseitige TLS-Authentifizierung für eine HTTP-API zu aktivieren, müssen Sie einen benutzerdefinierten Domänennamen für Ihre API konfigurieren. Sie können gegenseitige TLS für einen benutzerdefinierten Domänennamen aktivieren und dann den benutzerdefinierten Domänennamen für Clients bereitstellen. Um mithilfe eines benutzerdefinierten Domänennamens auf eine API zuzugreifen, für die gegenseitige TLS aktiviert ist, müssen Clients Zertifikate präsentieren, denen Sie in API-Anforderungen 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 ACM anfordern oder öffentliche oder selbstsignierte Zertifikate importieren. Gehen Sie zum Einrichten eines Zertifikats in ACM zu ACM. Wenn Sie ein Zertifikat importieren möchten, lesen Sie weiter im folgenden Abschnitt.

Verwenden eines importierten AWS Private Certificate Authority Zertifikats oder Zertifikats

Um ein in ACM importiertes Zertifikat oder ein Zertifikat von Mutual TLS verwenden AWS Private Certificate Authority zu können, benötigt API Gateway ein von ACM ownershipVerificationCertificate ausgestelltes. 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 keines habenownershipVerificationCertificate, gehen Sie zu, https://console.aws.amazon.com/acm/um eines 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. Die ownershipVerificationCertificate kann nicht als Serverzertifikat für eine andere gemeinsame TLS-Domäne in API Gateway verwendet werden. Wenn ein Zertifikat direkt wieder in ACM importiert wird, muss der Aussteller gleich bleiben.

Konfigurieren Ihres Truststore

Truststores sind Textdateien mit einer .pem-Dateierweiterung. Sie sind eine vertrauenswürdige Liste von Zertifikaten von Zertifizierungsstellen. Um gegenseitige TLS zu verwenden, erstellen Sie einen Truststore von X.509-Zertifikaten, denen Sie vertrauen, für den Zugriff auf Ihre API.

Sie müssen die vollständige Vertrauenskette vom ausstellenden CA-Zertifikat bis zum Stamm-CA-Zertifikat in Ihren Truststore aufnehmen. API Gateway akzeptiert Clientzertifikate, die von jeder Zertifizierungsstelle in der Vertrauenskette ausgestellt werden. 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:

API Gateway validiert eine Reihe von Zertifikatseigenschaften. Sie können Lambda-Genehmiger verwenden, um zusätzliche Prüfungen durchzuführen, wenn ein Client eine API aufruft, einschließlich der Prüfung, ob ein Zertifikat widerrufen wurde. API Gateway 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 cp-Befehl lädt certificates.pem in Ihren Amazon S3 S3-Bucket hoch:

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

Konfigurieren von gegenseitiger TLS für einen benutzerdefinierten Domänennamen

Um gegenseitiges TLS für eine HTTP-API zu konfigurieren, müssen Sie einen benutzerdefinierten regionalen Domänennamen und mindestens TLS-Version 1.2 für Ihre API verwenden. Weitere Informationen zum Erstellen und Konfigurieren eines benutzerdefinierten Domänennamens finden Sie unter Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway.

Nachdem Sie Ihren Vertrauensspeicher in Amazon S3 hochgeladen haben, können Sie Ihren benutzerdefinierten Domänennamen für die Verwendung von gegenseitigem TLS konfigurieren. Im Folgenden create-domain-namewird ein benutzerdefinierter Domainname mit gegenseitigem TLS erstellt:

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 Domänennamen erstellt haben, müssen Sie DNS-Datensätze und Basepath-Mappings für API-Vorgänge konfigurieren. Weitere Informationen hierzu finden Sie unter Einrichten eines regionalen benutzerdefinierten Domainnamens in API Gateway.

Aufrufen einer API mithilfe eines benutzerdefinierten Domänennamens, der gegenseitige TLS erfordert

Um eine API mit aktivierter gegenseitiger TLS aufzurufen, müssen Clients in der API-Anforderung ein vertrauenswürdiges Zertifikat präsentieren. Wenn ein Client versucht, Ihre API aufzurufen, sucht API Gateway in Ihrem Truststore nach dem Aussteller des Clientzertifikats. Damit API Gateway mit der Anforderung fortfahren kann, müssen sich der Aussteller des Zertifikats und die vollständige Vertrauenskette bis zum Stamm-CA-Zertifikats 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

Ihre 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 Anforderung mit einem 403-Statuscode verweigert. 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 Domänennamen aktualisieren, um eine neue Vertrauensspeicher-Version zu verwenden, gibt API Gateway Warnungen zurück, wenn Zertifikate ungültig sind.

API Gateway erzeugt Zertifikatswarnungen nur dann, wenn Sie Ihren Domänennamen aktualisieren. API Gateway benachrichtigt Sie nicht, wenn ein zuvor hochgeladenes Zertifikat abläuft.

Mit dem folgenden update-domain-nameBefehl 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'

Gegenseitige TLS deaktivieren

Um gegenseitige TLS für einen benutzerdefinierten Domänennamen zu deaktivieren, entfernen Sie den Truststore aus Ihrem benutzerdefinierten Domänennamen, wie im folgenden Befehl gezeigt.

Der folgende update-domain-nameBefehl aktualisiert einen benutzerdefinierten Domainnamen, um den Truststore aus Ihrem benutzerdefinierten Domainnamen zu entfernen:

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

Problembehebung bei gegenseitigen TLS für Ihre HTTP-API

Im Folgenden finden Sie Hinweise zur Fehlerbehebung bei Fehlern und Problemen, die bei der Aktivierung von „Gegenseitige TLS“ auftreten können.

Fehlerbehebung bei Zertifikatwarnungen

Wenn Sie einen benutzerdefinierten Domänennamen mit gegenseitiger TLS erstellen, gibt API Gateway Warnungen zurück, wenn Zertifikate im Truststore ungü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. Gegenseitige TLS ist weiterhin für Ihre API aktiviert, aber einige Clients 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 Subjekt im Zertifikat kann es nur einen Aussteller in API Gateway für gegenseitige TLS-Domänen 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 Support, um ein Ticket zu eröffnen.

Fehlerbehebung bei Statusmeldungen für Domänennamen

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

PENDING_OWNERSHIP_VERIFICATION: Dies bedeutet, dass Ihr zuvor verifiziertes Zertifikat abgelaufen ist und ACM es nicht automatisch erneuern konnte. Sie müssen das Zertifikat erneuern oder ein neues Zertifikat anfordern. Weitere Informationen zur Zertifikatserneuerung finden Sie im Leitfaden ACMs Fehlerbehebung bei der Erneuerung verwalteter Zertifikate.