SAML Certificate and Metadata Rotation

IdPs rotate signing certificates on a schedule (or when someone clicks "generate new cert"). If Descope still has the old cert, SAML assertions fail signature checks and login breaks — often with an assertion-handling error in Audits.

This page covers how to stay ahead of that (including expiry alerts), and how to rotate Descope's own SP keys when you need to.

Prefer configuring each tenant through the SSO Setup Suite. The suite (and Console metadata URL field) is the least painful way to keep IdP details current.

IdP Signing Certificate

Descope verifies every SAML assertion with the IdP's public certificate from the tenant's SSO config.

Metadata URL vs Static Certs

Upload certs statically (primary + additional) if you want expiry alerts. Use a metadata URL if you'd rather have hands-off auto-rotation — but then you won't get these expiry events.

When the IdP rotates its signing cert and updates its metadata, Descope picks up the new cert on the next fetch. Manual paste of Login URL / Entity ID / Certificate does not auto-update.

Certificate Expiry Alerts

For statically uploaded IdP certificates, Descope can emit a SAMLCertificateExpiry warn audit event as expiry approaches.

To alert customers (or your ops team):

1. Create a Management Flow whose Start action uses an event trigger on SAMLCertificateExpiry, and compose the notification from the event payload (triggeringEvent — see event triggers).
2. And/or route the warn audit event to a notification or audit streaming connector.

How to Rotate (Static Certs)

When you manage the IdP signing cert manually:

1. Add the new certificate to the additional certificates list (keep the current primary so login still works).
2. Switch the IdP to the new cert (or wait until the IdP starts signing with it).
3. Promote / set the new cert as primary in Descope if needed, then drop the old certificate from the list once the IdP no longer uses it.
4. Run a test login (Setup Suite connection test or a real SP-initiated login).

If the customer uses the Setup Suite, send them a fresh link and ask them to re-test after they finish the IdP-side rotation.

When Login Breaks After an IdP Change

1. Confirm the failure in Audits (LoginFailure / SAML assertion errors, often E062606).
2. On the IdP, check whether a new signing certificate is active and whether metadata was published with it.
3. In Descope (or the Setup Suite), refresh the connection:
   • Metadata URL: re-save or re-fetch so Descope reloads metadata.
   • Manual: follow How to Rotate (Static Certs) (or paste the new primary cert if you aren't using additional certs yet).
4. Run a test login.

Descope SP Signing and Encryption Keys

By default Descope generates SP keys for the tenant. The IdP uses Descope's public certificate (from SP metadata or download) to verify AuthnRequests and, when configured, to encrypt assertions.

Rotate or replace those keys when your security policy requires it, or when you've uploaded custom keys and need to renew them. Steps and PEM format: SAML Signing and Encryption Keys.

After you change SP keys:

1. Give the IdP the new public certificate (or point it at Descope's updated SP metadata URL).
2. Test SP-initiated login before rolling out to all users.

Leaving the IdP on the old SP cert is as broken as leaving Descope on an old IdP cert.

Checklist

• Choose metadata URL (auto-rotation, no expiry events) or static certs (expiry alerts + dual-cert cutover).
• If you need SAMLCertificateExpiry, ask Descope CS to enable the feature flag.
• Wire alerts: Management Flow on SAMLCertificateExpiry and/or an audit / messaging connector.
• For static rotation: additional certs → switch IdP → drop the old cert → test login.
• After SP key rotation: update the IdP with the new public cert / metadata, then test login.
• Keep SSO troubleshooting and Audits handy for E062604 / E062606.

Related

• SSO with SAML — metadata vs manual configuration
• SAML Signing and Encryption Keys — custom SP keys
• SAML Security — assertion validation and broader SAML model
• Management Flows — event-triggered automation
• SSO Setup Suite — customer self-service config and connection test
• SSO troubleshooting