This article will cover how to add a Security Assertion Markup Language (SAML) configuration that maps to your third-party identity provider in your Cutover instance.
Overview
Single-Sign-On (SSO) gives a user the ability to log into their Cutover instance by authenticating through their third-party identity provider (e.g., Okta) instead of using their email address and password. SAML authentication makes it possible for you to configure and troubleshoot SAML configurations in the Cutover platform, which are mapped to your third-party identity provider.
SAML Configuration Permissions
Global User Admin – Required for initial SAML setup, adding new SAML configurations, and managing the General tab (where SAML configurations are created).
SSO Admin – Can manage user role mappings and IdP certificates (including adding and removing). They cannot add new SAML configurations or manage the General tab within this process.
Add a SAML configuration
Navigate to Settings > SAML Configurations.
Click +Add SAML Configuration.
The Add a new SAML configuration modal displays.
Sources
When setting up SAML, you’ll need to provide metadata from your Identity Provider (IdP). In Cutover, you can choose the source of this configuration in one of the following ways:
Manual entry – Enter key IdP details (Entity ID, SSO URL, certificate) directly.
Use this if your IdP doesn’t provide metadata files or you only need to configure specific fields manually.XML upload – Upload the IdP metadata file (.xml) provided by your IdP.
Best for one-off or static configurations where you receive a file directly from your IdP administrator.URL – Provide a metadata URL if your IdP hosts the metadata online.
Recommended if your IdP supports a dynamic metadata URL — it keeps your configuration automatically updated when certificates or endpoints change.Raw text – Copy and paste the IdP metadata XML directly into Cutover.
Useful when you can’t upload a file or fetch via URL but have the XML contents available.
Best practice: Use the URL option whenever possible, as it ensures your configuration stays up to date automatically with any IdP changes (like certificate rotations).
General tab
The General tab can only be completed by a Global User Admin and includes the following fields:
Display Name: The display name of the SAML configuration.
IdP SSO Service URL: The URL of the client’s third-party identity provider.
Allowed clock drift in seconds: If the third-party identity provider’s system time runs ahead of Cutover’s system time, a value (in seconds) can be set to account for the difference when processing SAML information during authentication. The recommended value for this field is 30 seconds.
Attribute mappings: Maps the user attributes from the third-party identity provider to data in Cutover. To enable the auto-creation of users via SSO login, please ensure RBAC is enabled and the below attributes are mapped in JSON format (as illustrated in the example below) in this field:
first_name
last_name
unique_id
roles
email
Additional settings
Default: Selecting this option sets this SAML configuration to be used for the login button on Cutover's login page.
Use RBAC: Selecting this option auto-creates users on the first valid login and activates auto-assignment of roles based on SAML mappings, and enables the option to Purge Roles.
Attribute mappings example:
{ email: 'example', last_name: 'example', first_name: 'example', unique_id: 'example', roles: 'example, }
IdP Public Certificates tab
The IdP public certificate is used to verify signed SAML responses. This ensures that authentication messages truly come from your IdP and haven’t been altered, providing a secure and trusted login process for your users.
The IdP Public Certificates tab can be accessed when you add a new SAML configuration or edit an existing one. This can be managed by a Global User Admin and an SSO Admin.
To successfully save your SAML configuration, you must add the public certificate of your third-party Identity Provider (IdP). This certificate can usually be obtained from the IdP’s admin console or support documentation.
Note: A public certificate will be needed for each new SSO configuration.
Once all information has been entered and/or uploaded, click +Save.
Note: Please contact your Customer Success Manager (CSM) if you require any clarification on the process described above.
Once SSO has been set up, please contact the Support team for changes or troubleshooting help.
Add an IdP Public Certificate
You can add an IdP public certificate by clicking on a configuration in the SAML configurations list then choose the IdP Public Certificates tab.
Click +Add certificate.
Paste your public certificate details.
Note: Public certificates must follow the PEM file format. Certificates should always begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.
The certificate content (the encoded string) should be placed between these markers.
Example:
-----BEGIN CERTIFICATE-----
MIIDXTCCAkWgAwIBAgIJALaJk6n3Y2tqMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV
BAYTAkFVMRMwEQYDVQQIDApxdWVlbnNsYW5kMRAwDgYDVQQKDAdFeGFtcGxlMB4X
DTE2MDgxNzA4MjExNVoXDTI2MDgxNDA4MjExNVowRTELMAkGA1UEBhMCQVUxEzAR
BgNVBAgMCnF1ZWVuc2xhbmQxEDAOBgNVBAoMB0V4YW1wbGUwggEiMA0GCSqGSIb3
DQEBAQUAA4IBDwAwggEKAoIBAQDbz/mGgBfXhU3y...
...rest of certificate content...
-----END CERTIFICATE-----
Click +Save.
Delete an IdP Public Certificate
Go to the SAML Configurations list and select your configuration. Open the IdP Public Certificates tab and locate the certificate you want to remove.
Click the ✕ (cross icon) next to the certificate expiry date to delete it.
Warning: Deleting an IdP public certificate may disrupt user logins if the certificate is still in use. Always confirm that a replacement certificate has been added and tested before deleting the existing one.
Best Practices
To ensure a seamless experience, it is highly recommended that you rotate certificates proactively. Add the new certificate from your IdP before the old one expires. This allows Cutover to trust both the old and new certificates for a period, preventing any login failures during the transition.