Zertifikat auf dem Application Gateway ersetzen¶

Standardänderung: Ein TLS-Zertifikat eines veröffentlichten Workloads erneuern oder ersetzen. Das ist eine operative Aufgabe. Sie ändert ein Zertifikat im Key Vault des Gateways und bearbeitet das Konfigurations-Repository nicht, es sei denn, die Zertifikatsreferenz ändert sich (siehe Schritt 7).

Auswirkung: Der HTTPS-Listener des Workloads präsentiert das neue Zertifikat. Verwendet das Backend dasselbe Zertifikat, muss es gleichzeitig ersetzt werden.

Die Schritte verwenden ein Beispiel: einen Listener app1-https-listener, der ein Zertifikat app1-cert nutzt, gespeichert als Key-Vault- Zertifikat app1-example-com für den Hostnamen app1.example.com. Die Zertifizierungsstelle (CA) ist die CA, die deine Organisation verwendet.

Wer macht was¶

Aufgabe	Meist erledigt von
Das Zertifikat bei der CA bestellen, erneuern und bezahlen und die Domain validieren	Dem Kunden: dem Workload-Team oder einem zentralen Team, dem das CA-Konto gehört. Das CA-Konto und das Postfach, das die Validierungs-Mail erhält, gehören dem Kunden, nicht dem Plattform-Team.
Temporären Zugriff auf den Key Vault des Gateways geben und Key Vault und Gateway am Laufen halten	Dem Plattform-Team
Das Zertifikat importieren und das Gateway anstoßen	Dem Plattform-Team oder der Person, die das Zertifikat bestellt hat, mit temporärem Zugriff
Prüfen, dass die Anwendung funktioniert	Dem Workload-Team

Lege das fest, wenn die App veröffentlicht wird. Beide Betriebsmodelle sind unter Betriebsmodelle beschrieben.

Anfragefelder¶

Feld	Verwendung
Workload-Name und Hostname des Listeners	Welcher Listener das neue Zertifikat erhält
Zertifikatsname im Key Vault	Zum Beispiel `app1-example-com`
Ablaufdatum des aktuellen Zertifikats	Um die Änderung vor dem Ablauf zu planen
Verwendet das Backend dasselbe Zertifikat?	Wenn ja, plane, beide im selben Moment zu ersetzen
Wer bestellt das Zertifikat	Plattform-Team oder Workload-Team
Umgebung	Plattform-Umgebung (`canary` / `prod`)

Bevor du beginnst¶

Finde den Key Vault und das Zertifikat. Der Key Vault des Gateways wird von der Plattform erstellt (kv<company>agw<envshort><region>001, siehe Namen und state). Der Listener verweist über ssl_certificates.<cert>.key_vault_secret_id im Gateway-JSON auf das Zertifikat (Application Gateway).
Hole dir temporären erhöhten Zugriff auf den Key Vault: normalerweise eine Rolle wie Key Vault Administrator über PIM, oder Get-, List- und Schreibrechte auf Zertifikate und Secrets, wenn der Vault Access Policies nutzt. Die eigene Identität des Gateways hat nur Key Vault Secrets User.
Der Key Vault verweigert öffentlichen Zugriff außer für erlaubte Subnets. Arbeite aus einem erlaubten Netzwerk oder füge deine IP-Adresse temporär hinzu und entferne sie danach wieder.
Plane die Änderung rechtzeitig. Eine Erneuerung bei der CA, eine Domain-Validierungs-Mail und ein Merge im Key Vault können zusammen einen Tag dauern.

Schritte¶

1. Die Erneuerung bei der CA starten¶

Erneuere das bestehende Zertifikat bei deiner CA oder bestelle ein neues für denselben Hostnamen. Die CA verlangt einen Certificate Signing Request (CSR). Lass die Bestellung offen. Den CSR erstellst du im nächsten Schritt.

2. Eine neue Version im Key Vault erstellen und den CSR herunterladen¶

Öffne im Key Vault Certificates, wähle das Zertifikat und dann New version.
Behalte denselben Subject bei und ergänze die Organisationsattribute, die deine CA verlangt, im Subject (zum Beispiel O=<organisation>, C=<country>). Wähle den Inhaltstyp PKCS #12.
Erstelle die Version. Sie bleibt pending.
Öffne die ausstehende Version und wähle Operations > Download CSR. Speichere die Datei.

3. Den CSR an die CA senden und die Domain validieren¶

Füge den Inhalt des CSR in die Bestellung bei der CA ein.
Schließe die Domain-Validierung ab. Die CA sendet meist eine Mail an das Postfach des Domain- oder Systemadministrators, mit einem Link zur Genehmigung.
Hat die CA das Zertifikat signiert, erhältst du ein Archiv mit den Zertifikatsdateien: dem Serverzertifikat, einem oder mehreren Intermediate-Zertifikaten und dem Root-Zertifikat.

4. Die Zertifikate in einer Datei zusammenführen¶

Öffne die Dateien in einem einfachen Texteditor und füge sie in dieser Reihenfolge in einer Datei zusammen: zuerst das Serverzertifikat, dann das bzw. die Intermediate-Zertifikat(e) und zuletzt das Root-Zertifikat. Speichere sie als eine .cer-Datei, zum Beispiel app1-example-com-full.cer.

5. Den Signing Request im Key Vault mergen¶

Öffne die ausstehende Version des Zertifikats im Key Vault.
Wähle Operations > Merge Signing Request und wähle die kombinierte Datei.
Die Version erhält den Status Completed.

Der Key Vault enthält jetzt das neue Zertifikat. Das Gateway weiß es noch nicht.

6. Wenn der private Schlüssel außerhalb des Key Vaults erstellt wurde¶

Manchmal erstellt das Anwendungsteam den CSR und den privaten Schlüssel auf dem Backend (zum Beispiel für einen Reverse Proxy, der TLS terminiert) und sendet dir beides. Dann hat der Key Vault keine ausstehende Anfrage zum Mergen. Baue aus der signierten Zertifikatskette und dem Schlüssel eine PFX-Datei und importiere sie als neue Version des Zertifikats:

openssl pkcs12 -inkey private_key.key -in certificate.pem -export -out output.pfx

Die PEM-Datei muss die vollständige Kette in der Reihenfolge Serverzertifikat, Intermediate(s), Root enthalten. Stimme den Zeitpunkt des Austauschs mit dem Anwendungsteam ab, denn Gateway und Backend müssen sich gemeinsam ändern. Installiere dieselbe Kette auf dem Backend.

7. Das Gateway die neue Version verwenden lassen¶

Wie das Gateway die neue Version findet, hängt von der Secret-URI in key_vault_secret_id ab:

URI	Verhalten
Ohne Version (`https://<kv>.vault.azure.net/secrets/<name>`)	Das Gateway liest die neueste Version selbstständig. Es fragt den Key Vault regelmäßig ab, normalerweise innerhalb weniger Stunden.
Mit Version (`…/secrets/<name>/<version>`)	Das Gateway verwendet weiterhin diese Version. Ändere die URI im Gateway-JSON auf die neue Version, öffne einen pull request und deploye über Application Gateway.

Bevorzuge die URI ohne Version, damit eine Erneuerung keine Konfigurationsänderung braucht.

Damit das Gateway die neue Version sofort liest (zum Beispiel zum Testen), löse eine Änderung an der Gateway-Ressource aus, etwa indem du im Portal einen Tag hinzufügst. Speichere. Es kann bis zu etwa 15 Minuten dauern, bis die Änderung wirksam ist. Entferne den Tag danach wieder oder lass den nächsten hub-Lauf ihn entfernen, denn Tags, die nicht im Code stehen, werden entfernt, wenn Terraform anwendet (siehe Hub-Tags).

8. Das Ergebnis prüfen¶

Azure-Portal: Öffne das Gateway > Listeners > die Ansicht der TLS-Zertifikate. Das Zertifikat zeigt das neue Ablaufdatum (zum Beispiel ein Jahr in der Zukunft, je nach bestellter Gültigkeit).
Prüfe von außen Zertifikat und Kette mit einem Online-TLS-Checker oder mit openssl:

openssl s_client -connect app1.example.com:443 -servername app1.example.com </dev/null | openssl x509 -noout -dates -subject

Alle Prüfungen müssen bestehen: Das Zertifikat ist für den Hostnamen gültig, die Kette ist vollständig und nicht abgelaufen.
Bitte das Workload-Team, die Anwendung zu testen.

Rollback¶

Wähle im Key Vault die vorherige (ältere) Version des Zertifikats und mache sie zur aktuellen Version, oder lass das Gateway-JSON wieder auf deren URI zeigen, und stoße dann das Gateway erneut an. Tu das, bevor das alte Zertifikat abläuft.

Häufige Probleme¶

Symptom	Ursache
Das Gateway zeigt noch das alte Ablaufdatum	Die URI hat eine Version, oder das Gateway hat noch nicht abgefragt. Stoße es mit einer Tag-Änderung an oder aktualisiere die URI.
Merge Signing Request schlägt fehl	Die kombinierte Datei hat die falsche Reihenfolge, es fehlt das Intermediate-Zertifikat, oder sie wurde für einen anderen CSR gebaut. Merge in die Version, deren CSR du an die CA gesendet hast.
Der Browser zeigt eine unvollständige Kette	Das Intermediate-Zertifikat fehlt in der gemergten Datei.
Clients, die sich direkt mit dem Backend verbinden, scheitern	Das Backend verwendet noch das alte Zertifikat. Ersetze es gleichzeitig.
Du kannst den Key Vault nicht öffnen	Dir fehlt die Rolle oder der Netzwerkzugriff. Siehe Bevor du beginnst.

Wird die App zusätzlich über einen anderen Dienst veröffentlicht, der eine eigene Kopie des Zertifikats hat (zum Beispiel ein Authentifizierungs-Proxy in Entra ID), ersetze das Zertifikat auch dort.

Den nächsten Überraschungen vorbeugen¶

Trage das Ablaufdatum jedes Listener-Zertifikats in einen Kalender ein oder richte einen Alert auf den Zertifikatsablauf ein.
Führe pro Listener eine Liste: Hostname, CA, Owner und Erneuerungsdatum.