Ga naar inhoud

Een certificaat op de Application Gateway vervangen

Standaardwijziging: Een TLS-certificaat van een gepubliceerde workload verlengen of vervangen. Dit is een operationele taak. Het wijzigt een certificaat in de Key Vault van de gateway en past de configuratierepository niet aan, tenzij de certificaatverwijzing verandert (zie Stap 7).

Effect: de HTTPS-listener van de workload presenteert het nieuwe certificaat. Als de backend hetzelfde certificaat gebruikt, moet dat tegelijk worden vervangen.

De stappen gebruiken een voorbeeld: een listener app1-https-listener die een certificaat app1-cert gebruikt, opgeslagen als het Key Vault- certificaat app1-example-com voor de hostnaam app1.example.com. De certificaatautoriteit (CA) is de CA die jouw organisatie gebruikt.

Wie doet wat

Taak Meestal gedaan door
Het certificaat bij de CA bestellen, verlengen en betalen, en het domein valideren De klant: het workload team of een centraal team dat het CA-account beheert. Het CA-account en de mailbox die de validatiemail ontvangt zijn van de klant, niet van het platformteam.
Tijdelijke toegang tot de Key Vault van de gateway geven, en de Key Vault en gateway draaiend houden Het platformteam
Het certificaat importeren en de gateway triggeren Het platformteam, of degene die het certificaat heeft besteld, met tijdelijke toegang
Controleren of de applicatie werkt Het workload team

Beslis dit op het moment dat de app wordt gepubliceerd. Beide beheermodellen worden beschreven in Beheermodellen.

Aanvraagvelden

Veld Gebruik
Naam van de workload en hostnaam van de listener Welke listener het nieuwe certificaat krijgt
Certificaatnaam in de Key Vault Bijvoorbeeld app1-example-com
Vervaldatum van het huidige certificaat Om de wijziging te plannen voordat het verloopt
Gebruikt de backend hetzelfde certificaat? Zo ja, plan dan om beide op hetzelfde moment te vervangen
Wie bestelt het certificaat Platformteam of workload team
Omgeving Platformomgeving (canary / prod)

Voordat je begint

  • Zoek de Key Vault en het certificaat. De Key Vault van de gateway wordt door het platform aangemaakt (kv<company>agw<envshort><region>001, zie Naamgeving en state). De listener verwijst via ssl_certificates.<cert>.key_vault_secret_id in de gateway-JSON naar het certificaat (Application Gateway).
  • Vraag tijdelijke verhoogde toegang tot de Key Vault: normaal gesproken een rol zoals Key Vault Administrator via PIM, of Get-, List- en schrijfrechten op certificaten en secrets als de vault access policies gebruikt. De eigen identiteit van de gateway heeft alleen Key Vault Secrets User.
  • De Key Vault weigert publieke toegang behalve voor toegestane subnets. Werk vanaf een toegestaan netwerk, of voeg tijdelijk je IP-adres toe en verwijder het daarna weer.
  • Plan de wijziging ruim van tevoren. Een verlenging bij de CA, een domeinvalidatiemail en een Key Vault-merge kunnen samen een dag kosten.

Stappen

1. Start de verlenging bij de CA

Verleng het bestaande certificaat bij je CA, of bestel een nieuw certificaat voor dezelfde hostnaam. De CA vraagt om een certificate signing request (CSR). Laat de bestelling open staan. Je maakt de CSR in de volgende stap.

2. Maak een nieuwe versie in de Key Vault en download de CSR

  1. Open in de Key Vault Certificates, selecteer het certificaat en kies New version.
  2. Houd hetzelfde subject aan en voeg de organisatieattributen die je CA vereist toe aan het subject (bijvoorbeeld O=<organisation>, C=<country>). Kies het content type PKCS #12.
  3. Maak de versie aan. Die blijft pending.
  4. Open de pending versie en kies Operations > Download CSR. Sla het bestand op.

3. Stuur de CSR naar de CA en valideer het domein

  1. Plak de inhoud van de CSR in de bestelling bij de CA.
  2. Rond de domeinvalidatie af. De CA stuurt meestal een mail naar de mailbox van de domein- of systeembeheerder, met een link om goed te keuren.
  3. Als de CA het certificaat heeft ondertekend, ontvang je een archief met de certificaatbestanden: het servercertificaat, een of meer intermediate certificates en het rootcertificaat.

4. Combineer de certificaten in één bestand

Open de bestanden in een gewone teksteditor en zet ze in één bestand, in deze volgorde: eerst het servercertificaat, dan de intermediate certificate(s), en het rootcertificaat als laatste. Sla het op als één .cer-bestand, bijvoorbeeld app1-example-com-full.cer.

5. Voeg de signing request samen in de Key Vault

  1. Open de pending versie van het certificaat in de Key Vault.
  2. Kies Operations > Merge Signing Request en selecteer het gecombineerde bestand.
  3. De versie krijgt de status Completed.

De Key Vault bevat nu het nieuwe certificaat. De gateway weet dat nog niet.

6. Als de private key buiten de Key Vault is aangemaakt

Soms maakt het applicatieteam de CSR en de private key aan op de backend (bijvoorbeeld voor een reverse proxy die TLS afhandelt), en stuurt beide naar jou. Dan heeft de Key Vault geen pending aanvraag om samen te voegen. Bouw een PFX-bestand van de ondertekende certificaatketen en de key, en importeer dat als een nieuwe versie van het certificaat:

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

Het PEM-bestand moet de volledige keten bevatten in de volgorde servercertificaat, intermediate(s), root. Spreek het moment van vervanging af met het applicatieteam, want de gateway en de backend moeten samen wijzigen. Installeer dezelfde keten op de backend.

7. Zorg dat de gateway de nieuwe versie gebruikt

Hoe de gateway de nieuwe versie vindt, hangt af van de secret-URI in key_vault_secret_id:

URI Gedrag
Zonder versie (https://<kv>.vault.azure.net/secrets/<name>) De gateway leest zelf de nieuwste versie. Hij pollt de Key Vault, normaal gesproken binnen een paar uur.
Met een versie (…/secrets/<name>/<version>) De gateway blijft die versie gebruiken. Wijzig de URI in de gateway-JSON naar de nieuwe versie, open een pull request en deploy via Application Gateway.

Geef de voorkeur aan de URI zonder versie, zodat een verlenging geen configuratiewijziging nodig heeft.

Om de gateway de nieuwe versie direct te laten lezen (bijvoorbeeld om te testen), trigger je een wijziging op de gatewayresource, zoals het toevoegen van een tag in de portal. Sla het op. Het kan tot ongeveer 15 minuten duren voordat de wijziging effect heeft. Verwijder daarna de tag weer, of laat de volgende hub-run hem verwijderen, want tags die niet in code staan worden verwijderd wanneer Terraform toepast (zie Hub-tags).

8. Controleer het resultaat

  • Azure portal: open de gateway > Listeners > de weergave met TLS-certificaten. Het certificaat toont de nieuwe vervaldatum (bijvoorbeeld een jaar vooruit, afhankelijk van de geldigheid die je hebt besteld).
  • Controleer van buitenaf het certificaat en de keten met een online TLS-checker, of met openssl:
openssl s_client -connect app1.example.com:443 -servername app1.example.com </dev/null | openssl x509 -noout -dates -subject
  • Alle controles moeten slagen: het certificaat is geldig voor de hostnaam, de keten is compleet en niet verlopen.
  • Vraag het workload team om de applicatie te testen.

Terugdraaien

Selecteer de vorige (oudere) versie van het certificaat in de Key Vault en maak die de huidige versie, of laat de gateway-JSON terugwijzen naar de URI ervan, en trigger de gateway daarna opnieuw. Doe dit voordat het oude certificaat verloopt.

Veelvoorkomende problemen

Symptoom Oorzaak
De gateway toont nog de oude vervaldatum De URI heeft een versie, of de gateway heeft nog niet gepolld. Trigger hem met een tagwijziging, of werk de URI bij.
Merge Signing Request mislukt Het gecombineerde bestand heeft de verkeerde volgorde, mist het intermediate certificate, of is gebouwd voor een andere CSR. Voeg samen in de versie waarvan je de CSR naar de CA hebt gestuurd.
De browser toont een onvolledige keten Het intermediate certificate ontbreekt in het samengevoegde bestand.
Clients die rechtstreeks met de backend verbinden falen De backend gebruikt nog het oude certificaat. Vervang het tegelijk.
Je kunt de Key Vault niet openen Je mist de rol of de netwerktoegang. Zie Voordat je begint.

Als de app ook via een andere service wordt gepubliceerd die een eigen kopie van het certificaat heeft (bijvoorbeeld een authenticatieproxy in Entra ID), vervang het certificaat daar dan ook.

Voorkom de volgende verrassing

  • Zet de vervaldatum van het certificaat van elke listener in een agenda, of stel een alert in op het verlopen van certificaten.
  • Houd per listener een lijst bij: hostnaam, CA, eigenaar en verlengingsdatum.