Konfigurieren der gegenseitigen TLS-Authentifizierung für eine REST-API

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. Gegenseitige TLS ist eine gemeinsame Voraussetzung für Internet of Things(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.

Wichtig

Standardmäßig können Clients Ihre API mithilfe des execute-api-Endpunkts aufrufen, den API Gateway für Ihre API generiert. Um sicherzustellen, dass Clients nur mithilfe eines benutzerdefinierten Domänennamens mit gegenseitiger TLS auf Ihre API zugreifen können, deaktivieren Sie den execute-api-Standardendpunkt. Weitere Informationen hierzu finden Sie unter Deaktivieren des Standardendpunkts für eine REST-API.

Voraussetzungen für gegenseitige TLS

Um gegenseitige TLS zu konfigurieren, benötigen Sie:

• Einen benutzerdefinierten Domänennamen

• Mindestens ein in AWS Certificate Manager konfiguriertes Zertifikat für Ihren benutzerdefinierten Domänennamen

• Ein in Amazon S3 konfigurierter und hochgeladener Truststore

Benutzerdefinierte Domänennamen

Um die gegenseitige TLS-Authentifizierung für eine REST-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 Einrichten von benutzerdefinierten Domänennamen für REST-APIs.

Benutzen von AWS Certificate Manager-ausgestellten Zertifikaten

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 oder AWS Private Certificate Authority-Zertifikats

Um ein in ACM importiertes Zertifikat oder ein Zertifikat vonAWS Private Certificate Authority mit gegenseitigem TLS zu verwenden, benötigt API Gateway eine ownershipVerificationCertificate von ACM ausgestellt. 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. Wenn Sie noch keine ownershipVerificationCertificate haben, navigieren Sie zuhttps://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. 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:

• SHA-256 oder stärker

• RSA-2048 oder stärker

• ECDSA-256 oder stärker

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:

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

Mit dem folgenden AWS CLI-CLI-Befehl wird certificates.pem in Ihren Amazon-S3-Bucket hochgeladen.

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

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

Um gegenseitiges TLS für eine REST-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 Domänennamens in API Gateway.

Anmerkung

Gegenseitiges TLS wird für private APIs nicht unterstützt.

Nachdem Sie Ihren Vertrauensspeicher in Amazon S3 hochgeladen haben, können Sie Ihren benutzerdefinierten Domänennamen für die Verwendung von gegenseitigem TLS konfigurieren. 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 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 Domänennamens 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:

• nicht vertrauenswürdig ist

• abgelaufen ist

• keinen unterstützten Algorithmus verwendet

Anmerkung

API Gateway überprüft nicht, ob ein Zertifikat widerrufen 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 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 AWS CLI-Befehl wird ein benutzerdefinierter Domänenname aktualisiert, um eine neue Truststore-Version zu verwenden.

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

aws apigateway update-domain-name \
    --domain-name api.example.com \
    --patch-operations op='replace',path='/mutualTlsAuthentication/truststoreUri',value=''

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 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 in ACM importiert haben und die Validierung fehlgeschlagen ist, da das neue Zertifikat über ein SAN (alternativer Antragstellername) verfügt, das nicht von der ownershipVerificationCertificate abgedeckt ist oder der Betreff oder die SANs im Zertifikat decken den Domänennamen nicht ab. 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.