For SAML-based authentication, Mosaic uses an X.509 certificate to sign the responses it sends to a service provider (SP). When configured, Mosaic also signs the assertions within those responses.
Regularly rotating signing certificates limits how long a signing key remains in use and helps prevent authentication disruptions caused by certificate expiration. Each SAML client can have up to two certificates, allowing you to prepare and distribute a replacement before switching the certificate used for signing.
Each signing certificate is valid for two years and has one of the following statuses:
- Active: The certificate that Mosaic currently uses for all configured SAML signing.
- Standby: An optional replacement certificate that you can distribute to your service provider before activating it.
For each certificate, the Admin Portal displays its status, creation date, and expiration date.
Plan the rotation in advance. For example, when external teams or change approvals are involved, generate and distribute the Standby certificate at least 30 days before the Active certificate expires.
Then follow these steps to rotate the certificate without interrupting SAML authentication:
- Generate a new certificate. Mosaic adds it to the client as the Standby certificate.
- Configure your service provider to trust the Standby certificate. You can obtain it from the Admin Portal or from the client's IDP metadata.
- Confirm that the service provider trusts both certificates.
- Activate the Standby certificate during a period when you can monitor SAML authentication and respond to issues. It becomes Active, and the previously Active certificate becomes Standby.
- Test a complete SAML authentication flow with the new Active certificate.
- Keep the previous certificate as Standby for an observation period, for example, 24–48 hours, so you can reactivate it if rollback is required. Once the new certificate is confirmed to work, delete the old Standby certificate to make room for the next rotation.
Before activating the Standby certificate, make sure your service provider trusts both certificates. Activating a certificate before updating the service provider may interrupt SAML authentication.
You can manage signing certificates from the settings of a SAML client in the Admin Portal. Go to Applications > your application > Clients.
Open the SAML client and use the available certificate actions to:
- Generate a new Standby certificate.
- Activate the Standby certificate and make the current Active certificate the new Standby certificate.
- Delete a certificate that is no longer required.
Starting 45 days before an Active signing certificate expires, the Admin Portal displays alerts at both the application and client levels:
- On the Applications page, the application row displays a warning (yellow) when one or more clients have certificates or keys that are approaching expiration. After expiration, it displays an alert (red) indicating that certificates or keys have already expired. Both messages direct you to update them in the affected clients' settings.
- In Applications > your application > Clients, the affected client row displays a warning (yellow) with the signing certificate's expiration date and prompts you to generate a new certificate. After expiration, it displays an urgent alert (red) that prompts you to generate and activate a new certificate.
The IDP metadata URL does not change when you generate or activate a certificate. When a client has both an Active and a Standby certificate, Mosaic publishes both certificates in its IDP metadata.
SAML metadata does not distinguish between the Active and Standby certificates. Use the Admin Portal or the API to determine which certificate is currently Active. Although both certificates appear in the metadata, Mosaic uses only the Active certificate for signing.
If your service provider refreshes IDP metadata automatically, confirm that it has imported both certificates before activating the Standby certificate. If it does not refresh metadata automatically, add the Standby certificate to the service provider manually.
If your service provider supports only one certificate at a time, coordinate the certificate update and activation within a maintenance window.
You can also generate, activate, and delete SAML signing certificates using APIs. The client object exposes the status, creation date, and expiration date of each certificate.
Use the API reference that corresponds to the type of SAML client you manage:
Certificate management operations performed through the API are also recorded in Admin Activity.
Some existing tenants may still have SAML clients that use the legacy shared certificate, which expires in November 2026. For these tenants, the Admin Portal displays warnings on the Applications page and in the client table while the legacy certificate remains Active.
To migrate a client:
- Open the affected SAML client and generate a Standby certificate.
- Configure the service provider to trust the new certificate.
- Activate the new certificate.
- Confirm that SAML authentication succeeds.
- Delete the legacy certificate when it is no longer required.
The warnings remain visible until the legacy shared certificate is no longer Active.
Mosaic records certificate generation, activation, and deletion in Admin Activity, whether the action was performed in the Admin Portal or through an API. See View admin activity.
Certificate rotation changes only the SAML client configuration. It does not require changes to Journeys or other authentication-flow steps, and it does not change the end-user authentication experience.