> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate your SAML signing certificate

> Replace an expiring or rotated SAML signing certificate on your SSO connection without opening a support ticket.

If your SSO connection uses SAML, your identity provider signs every login with a signing certificate that ION verifies. When that certificate is approaching expiry, or your security team rotates it on a schedule, you need to give ION the new certificate.

OIDC connections don't use a signing certificate. Their keys rotate automatically, so there's nothing to do.

## 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.

<Warning>
  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.
</Warning>

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.

<Note>
  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`.
</Note>

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](https://support.firstresonance.io/) with the fingerprint ION displayed and the time of the change.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://support.firstresonance.io/).
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](https://support.firstresonance.io/).
  </Accordion>
</AccordionGroup>

## Provider-specific notes

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

* [Set up SSO](/administration/authentication-settings/set-up-sso)
* [Disable SSO](/administration/authentication-settings/disable-sso)