Multiple signing certificates for SAML connections
- Category
- SSO
- Published
SAML connections now support multiple certificates. Add your identity provider’s next signing certificate before it rotates keys, so SSO sign-ins keep working without downtime.
A SAML IdP signs every SSO response with a private key, and Clerk verifies it with the certificate stored on the enterprise connection. Until now, a connection held only one certificate, so a key rotation meant replacing it at exactly the moment the IdP switched: upload the new certificate too early, and sign-ins would fail while the IdP still used the old key; upload it too late, and they would fail once the IdP started using the new key.
A SAML enterprise connection now trusts up to five signing certificates at once. Add the IdP's next certificate ahead of time, let the IdP switch whenever it does, and remove the old certificate afterward. No sign-in is rejected on either side of the switch.
How it works
Changing a connection's certificates replaces the entire list with the certificates you provide. If an update doesn't include certificates, the list stays the same. That's also how you stop trusting a leaked key: remove it from the list. Uploads take a single certificate or a PEM bundle, which many IdPs export when they list more than one signing key; every certificate in the bundle becomes an entry. Each certificate shows its expiry, with a warning when it expires within 30 days.
Where to manage certificates
- Clerk Dashboard: the Certificates list on a SAML connection's SSO tab shows every trusted certificate with its expiry and lets you add one from a file (a PEM bundle adds several) or remove one.
- Organization admins: the Security tab of
<OrganizationProfile />and the self-serve SSO setup show the same list for their Organization's connection, with the same upload and remove actions. - Backend API: pass the full list as
idp_certificateswhen you create or update an enterprise connection; responses include each certificate with its validity window. The singleidp_certificatefield keeps working, accepts a PEM bundle, and is deprecated.
Get started
Multiple certificates are available on every instance with SAML enterprise connections; existing connections keep their current certificate as the only entry until you add more. Read the certificate rotation guide for the step-by-step rotation and the API details.