SAML certificate renewal: the maintenance task that logs everyone out

Every SAML integration has at least one certificate, and every certificate expires. The failure mode is unpleasant: at the moment of expiry, every login through that integration fails at once, with an error that looks like a configuration problem.

Certificate renewal is not hard. It is just easy to postpone until it is an incident. This article covers the procedure that avoids the incident.

The certificates involved

SAML metadata can carry keys for two purposes:

Most integrations only use the signing certificate. When people say "the SAML certificate", they mean that one — the IdP's signing key, which every SP holds a copy of.

There can also be a certificate used by the SP to sign its AuthnRequests, but it is less common and separate from the two above.

Why expiry is an outage

• The SP validates every response against the certificate it has cached.
• When the IdP rotates its key and the SP still has the old one, signature validation fails.
• The error surfaces as "invalid signature", "certificate expired" or a generic login failure — rarely as "the certificate is out of date".
• Every user of that integration is affected simultaneously.

The same thing happens in reverse if the IdP still has an old SP encryption certificate.

The overlap procedure

The safe renewal uses two certificates at once:

1. Generate the new key pair and certificate at the IdP.
2. Publish both certificates in the IdP's metadata — the metadata format allows multiple KeyDescriptor elements, and SPs are expected to accept any of them.
3. Update the SP with the new metadata (or let it refresh from the URL).
4. Verify that logins still work with the new certificate in place.
5. Remove the old certificate from the metadata after the overlap window.
6. Verify again, then archive the old key.

The overlap window should be at least:

• the SP's metadata refresh interval, plus
• the time it takes your support team to notice a problem, plus
• a safety margin — days, not minutes.

If the SP cannot hold two certificates, you need a maintenance window instead. Better to discover that during a test than during an outage.

What to check before you start

• Who owns the certificate? The IdP team, the SP vendor, or a shared trust team. In enterprise deals this is often not obvious.
• How does the SP get metadata? A URL it refreshes, or a file uploaded once. The second is the one that goes stale.
• Does the SP support multiple KeyDescriptors? Some do not, and require a scheduled change.
• Is there an encryption certificate too? If assertions are encrypted, the SP's key is also in play.
• What is the rollback? Until the old certificate is removed, rolling back is just restoring the old metadata.

Monitoring

Certificate expiry should be a monitored metric, not a calendar note:

• Track every certificate in every SAML integration with its expiry date.
• Alert at 90, 30, 7 and 1 day before expiry.
• Include the certificate in the same inventory as TLS certificates — it is the same class of risk.
• After any rotation, confirm the SP is using the new certificate (a test login, not just a metadata check).

What vendors do

Most identity providers publish a rotation guide with their own default validity and notification windows — Microsoft Entra ID, Okta and Auth0 all have one. Read the one for your IdP rather than assuming a number; the procedure above is the same, but the defaults are not.

Casdoor publishes metadata per application that includes the signing certificate, and the application's SAML tab is where the metadata URL comes from. When rotating, keep the old key published until every SP has refreshed — the metadata format supports it.

Related reading: SAML metadata explained, SAML assertions and set up Casdoor as a SAML IdP.