Replace a Certificate on the Application Gateway¶
Standard change: Renew or replace a TLS certificate of a published workload. This is an operational task. It changes a certificate in the gateway's Key Vault and does not edit the configuration repository, unless the certificate reference changes (see Step 7).
Effect: the HTTPS listener of the workload presents the new certificate. If the backend uses the same certificate, it must be replaced at the same time.
The steps use an example: a listener app1-https-listener that uses a certificate app1-cert, stored as the Key Vault
certificate app1-example-com for the host name app1.example.com. The certificate authority (CA) is whichever CA your
organisation uses.
Who does what¶
| Task | Usually done by |
|---|---|
| Order, renew and pay for the certificate at the CA, and validate the domain | The customer: the workload team or a central team that owns the CA account. The CA account and the mailbox that receives the validation mail belong to the customer, not to the platform team. |
| Give temporary access to the gateway Key Vault, and keep the Key Vault and gateway running | The platform team |
| Import the certificate and trigger the gateway | The platform team, or the person who ordered the certificate, with temporary access |
| Check that the application works | The workload team |
Decide this when the app is published. Both operating models are described in Operating models.
Request fields¶
| Field | Use |
|---|---|
| Workload name and listener host name | Which listener gets the new certificate |
| Certificate name in the Key Vault | For example app1-example-com |
| Expiry date of the current certificate | To plan the change before it expires |
| Does the backend use the same certificate? | If yes, plan to replace both at the same moment |
| Who orders the certificate | Platform team or workload team |
| Environment | Platform environment (canary / prod) |
Before you start¶
- Find the Key Vault and the certificate. The gateway Key Vault is created by the platform
(
kv<company>agw<envshort><region>001, see Naming and state). The listener refers to the certificate throughssl_certificates.<cert>.key_vault_secret_idin the gateway JSON (Application Gateway). - Get temporary elevated access to the Key Vault: normally a role such as Key Vault Administrator through PIM, or Get, List and write permissions on certificates and secrets if the vault uses access policies. The gateway's own identity only has Key Vault Secrets User.
- The Key Vault denies public access except for allowed subnets. Work from an allowed network, or add your IP address temporarily and remove it afterwards.
- Plan the change in good time. A renewal at the CA, a domain validation mail and a Key Vault merge together can take a day.
Steps¶
1. Start the renewal at the CA¶
Renew the existing certificate at your CA, or order a new one for the same host name. The CA asks for a certificate signing request (CSR). Keep the order open. You create the CSR in the next step.
2. Create a new version in the Key Vault and download the CSR¶
- In the Key Vault, open Certificates, select the certificate and choose New version.
- Keep the same subject and add the organisation attributes your CA requires to the subject (for example
O=<organisation>, C=<country>). Choose the content type PKCS #12. - Create the version. It stays pending.
- Open the pending version and choose Operations > Download CSR. Save the file.
3. Send the CSR to the CA and validate the domain¶
- Paste the content of the CSR into the CA order.
- Complete the domain validation. The CA usually sends a mail to the mailbox of the domain or system administrator, with a link to approve.
- When the CA has signed the certificate, you receive an archive with the certificate files: the server certificate, one or more intermediate certificates and the root certificate.
4. Combine the certificates in one file¶
Open the files in a plain text editor and put them in one file, in this order: the server certificate first, then the
intermediate certificate(s), and the root certificate last. Save it as one .cer file, for example
app1-example-com-full.cer.
5. Merge the signing request in the Key Vault¶
- Open the pending version of the certificate in the Key Vault.
- Choose Operations > Merge Signing Request and select the combined file.
- The version gets status Completed.
The Key Vault now holds the new certificate. The gateway doesn't know yet.
6. If the private key was created outside the Key Vault¶
Sometimes the application team creates the CSR and the private key on the backend (for example for a reverse proxy that terminates TLS), and sends both to you. Then the Key Vault has no pending request to merge. Build a PFX file from the signed certificate chain and the key, and import it as a new version of the certificate:
openssl pkcs12 -inkey private_key.key -in certificate.pem -export -out output.pfx
The PEM file must contain the full chain in the order server certificate, intermediate(s), root. Agree the moment of replacement with the application team, because the gateway and the backend must change together. Install the same chain on the backend.
7. Make the gateway use the new version¶
How the gateway finds the new version depends on the secret URI in key_vault_secret_id:
| URI | Behaviour |
|---|---|
Without a version (https://<kv>.vault.azure.net/secrets/<name>) |
The gateway reads the newest version by itself. It polls the Key Vault, normally within a few hours. |
With a version (…/secrets/<name>/<version>) |
The gateway keeps using that version. Change the URI to the new version in the gateway JSON, open a pull request and deploy through Application Gateway. |
Prefer the URI without a version, so a renewal doesn't need a configuration change.
To make the gateway read the new version right away (for example to test), trigger a change on the gateway resource, such as
adding a tag in the portal. Save it. It can take up to about 15 minutes before the change is effective. Then remove the
tag again, or let the next hub run remove it, because tags that aren't in code are removed when Terraform applies
(see Hub tags).
8. Check the result¶
- Azure portal: open the gateway > Listeners > the TLS certificates view. The certificate shows the new expiry date (for example one year ahead, depending on the validity you ordered).
- From outside, check the certificate and chain with an online TLS checker, or with
openssl:
openssl s_client -connect app1.example.com:443 -servername app1.example.com </dev/null | openssl x509 -noout -dates -subject
- All checks must pass: the certificate is valid for the host name, the chain is complete and not expired.
- Ask the workload team to test the application.
Roll back¶
Select the previous (older) version of the certificate in the Key Vault and make it the current version, or point the gateway JSON back to its URI, then trigger the gateway again. Do this before the old certificate expires.
Common problems¶
| Symptom | Cause |
|---|---|
| The gateway still shows the old expiry date | The URI has a version, or the gateway has not polled yet. Trigger it with a tag change, or update the URI. |
| Merge Signing Request fails | The combined file is in the wrong order, is missing the intermediate certificate, or was built for another CSR. Merge into the version whose CSR you sent to the CA. |
| Browser shows an incomplete chain | The intermediate certificate is missing in the merged file. |
| Clients that connect to the backend directly fail | The backend still uses the old certificate. Replace it at the same time. |
| You can't open the Key Vault | You lack the role or the network access. See Before you start. |
If the app is also published through another service that has its own copy of the certificate (for example an authentication proxy in Entra ID), replace the certificate there as well.
Prevent the next surprise¶
- Put the expiry date of each listener certificate in a calendar, or set up an alert on certificate expiry.
- Keep a list per listener: host name, CA, owner and renewal date.