Rotate your SAML signing certificate - ION Manual

When you’ll need to do this

• Certificate expiry. Most IdP signing certificates are valid for one to three years. Your IdP or security team issues a replacement before the old one expires.
• Scheduled key rotation. Routine security hygiene, or a response to a suspected key compromise.
• IdP changes. Switching identity providers, or upgrading the signing algorithm (for example, moving from SHA-1 to SHA-256).
• Auto-rolled keys. Your IdP changed its signing key on its own (for example, Microsoft Entra auto-rolled its certificate).

Before you start

The Rotate certificate button is only visible to org administrators with SSO management permission. Rotating the certificate requires updating both your IdP and ION at roughly the same time. If they’re out of sync, logins fail.

ION holds one signing certificate per connection at a time. There’s no overlap period where both the old and new certificates are valid. New sign-ins briefly fail in the window between your IdP switching to the new key and ION being updated to match. Anyone already signed in stays signed in; the certificate is only checked on fresh logins.

Keep your previous certificate available until you’ve confirmed a successful login. Rolling back means pasting the old certificate back.

What you’ll need

From your IdP administrator, get one of the following for the new certificate:

• The new X.509 certificate in PEM format (a text block beginning with -----BEGIN CERTIFICATE-----), or
• Your IdP’s SAML 2.0 metadata XML (beginning with <?xml or <EntityDescriptor).

Either format works. ION detects which one you’ve provided. A few formatting tips that prevent common errors:

• Paste the certificate as text, not a binary file. Several IdPs (Microsoft Entra ID, ADFS) download the certificate as a binary .cer/.crt file. Convert it to PEM first: openssl x509 -inform der -in cert.cer -out cert.pem. Or paste the metadata XML instead.
• PEM vs. metadata XML is more than a formatting choice. A PEM updates only the signing certificate. Pasting metadata XML re-points ION at the whole document, which can also change sign-in endpoints and attribute mappings. For a routine certificate swap, prefer the PEM.
• Paste only the certificate block. If using PEM, include everything from -----BEGIN CERTIFICATE----- through -----END CERTIFICATE----- with no extra text above or below.

Rotate the certificate

1. In ION, go to Settings > Organization > Authentication.
2. In the Enterprise SSO card, click Rotate certificate.
3. Paste the new PEM certificate or SAML metadata XML into the dialog, or use Upload from file to select it. ION confirms the format it detected below the input.
4. Have your IdP administrator activate the new signing key.
5. Click Rotate. ION immediately starts verifying logins with the new certificate and displays a SHA-256 fingerprint of the new certificate.

ION’s fingerprint is SHA-256, but most IdP consoles (Okta, Microsoft Entra, ADFS) display a SHA-1 thumbprint, so the two won’t match by eye even when everything is correct. To compare, generate the SHA-256 yourself: openssl x509 -noout -fingerprint -sha256 -in cert.pem.

6. Ask someone (not yourself) to sign out and sign back in through SSO to verify the new certificate works.

If sign-ins start failing

This is recoverable and does not affect anyone already signed in.

• Most likely cause: ION and your IdP are temporarily out of sync. One is using the new certificate and the other is still on the old one.
• Fastest fix: Open Rotate certificate again and paste the previous certificate back. New sign-ins recover immediately. Then retry the rotation once both sides are ready to switch together.
• If logins still fail after both sides are confirmed on the new certificate, contact support with the fingerprint ION displayed and the time of the change.

Frequently asked questions

Will this log everyone out? No. The signing certificate is only checked when someone signs in fresh. Everyone with an active session keeps working uninterrupted.

Can I load the new certificate ahead of time? Not without a brief interruption. Because ION holds only one certificate at a time, loading the new one before your IdP starts signing with it causes new sign-ins to fail until the IdP catches up. Switch both sides together instead.

What if I don't see the Rotate certificate button? The action is restricted to administrators with SSO management permission. Ask an admin on your team or contact support.

PEM or metadata XML: which should I use? For a routine certificate swap, paste the PEM. It updates only the signing certificate and leaves the rest of your connection untouched. Use metadata XML only when you intend to refresh the whole connection (new endpoints or attribute mappings).

My IdP is rolling over and has two certificates. Which do I use? Paste the certificate your IdP will sign with after the cutover, coordinated with the switch.

What exactly does this rotate? This action updates only the IdP signing certificate ION uses to verify login tokens. It does not change ION’s request-signing certificate or any assertion-encryption keys. If you need to rotate those, contact support.

Provider-specific notes

Microsoft Entra ID (Azure AD), including GovCloud

Entra downloads its certificate as a binary .cer (DER) file. Convert it to PEM, or use the federation metadata. Entra auto-rolls its signing certificate and lists multiple certificates in its federation metadata during the overlap, so paste the one it will use after the switch. GovCloud tenants live under login.microsoftonline.us.

Okta

Generate the next certificate in Okta, then paste its signing certificate (PEM) or Okta’s metadata URL/file. Okta metadata lists both encryption and signing certificates. ION automatically picks the signing one.

ADFS

ADFS’s AutoCertificateRollover publishes a primary and secondary token-signing certificate, exported as binary .cer (DER). Convert to PEM and paste the one that will be primary after the rollover.

Google Workspace / other SAML providers

Download the SAML app’s signing certificate as PEM and paste it. If your provider only offers metadata, paste the metadata XML.