Single Sign-On (SSO)

Single Sign-On (SSO) is available on the Enterprise plan. Chromatic enables it on an organization account so your team can authenticate through a corporate identity provider (IdP).

Your team signs in through a custom subdomain such as mycompany.chromatic.com. If you do not know the subdomain, ask an account Admin or project Owner. You can also contact Chromatic Support through in-app chat or email.

Supported SSO providers

Chromatic works with any SAML 2.0 compliant Identity Provider, including:

• Okta
• Microsoft Entra ID (Azure AD)
• Google Workspace
• OneLogin
• PingOne
• JumpCloud
• Keycloak
• CyberArk
• Generic SAML 2.0 IdP
• Generic OIDC IdP

If your provider is not listed, contact Chromatic Support through in-app chat or email to check compatibility.

Logging in with SSO

Once SSO is enabled, account collaborators can sign in two ways:

1. Direct subdomain link: https://{YOUR-SUBDOMAIN}.chromatic.com/start Replace {YOUR-SUBDOMAIN} with the subdomain assigned to your account.

2. IdP dashboard: Click the Chromatic application tile in your SSO provider’s portal.

SCIM synchronizes account collaborator changes from your SSO provider. Use Teams to grant SCIM-synced groups access to specific projects.

What changes when SSO is enabled

SSO changes how existing account collaborators authenticate. Profiles that used a Git provider lose their account and project memberships during the cutover, and Chromatic disconnects their Git identities.

Each account collaborator must sign in through SAML to regain access. If the account needs Git connections, Chromatic configures them separately for the SSO setup.

Troubleshooting login issues

• Confirm that your profile is provisioned to the Chromatic application and that its IdP group has the required permissions.
• Double-check that you are using the correct subdomain in the login URL. It must exactly match the one assigned to your account.
• Stale cookies or cached data can block login. Clear your browser’s cache and cookies, or sign in from a private window.
• If your account has IP restrictions, connect to your corporate network as required by your company’s policy.
• If your account limits access by domain, your email domain must be on its allow list. Contact Support to add a non-generic contractor domain.

How Chromatic matches SAML profiles

Chromatic identifies SAML profiles by the SAML NameID (or idp_id attribute) alone. The match is case-insensitive. Use a persistent, immutable profile identifier from your IdP.

Your IdP must also send email and firstName or lastName attributes in the SAML assertion. Chromatic requires them to create a profile, but doesn’t use them to match existing profiles.

What happens when the NameID (or idp_id) changes?

Chromatic treats an unrecognized NameID as a new person and creates a new profile. The previous profile’s history and permissions don’t carry over, even when the email and name attributes are unchanged.

Use a persistent, unchanging NameID or idp_id attribute.

What happens when the corporate domain changes (e.g., from @oldcompany.com to @newcompany.com)?

If your SAML NameID is an email address, changing domains changes every NameID. Chromatic then creates duplicate profiles without the original history and permissions. Configure your IdP to send a persistent, immutable NameID before the change, and contact Chromatic Support about the new email and subdomain.

Before changing the domain, change one test profile’s email and verify that it still opens the existing profile.

Provision profiles with JIT or SCIM

Chromatic supports two provisioning methods. Just-in-Time (JIT) provisioning creates a profile when someone signs in through SSO for the first time.

System for Cross-domain Identity Management (SCIM) pushes profiles and groups from your IdP before their first sign-in. It can assign roles and remove access when your IdP disables someone. Directory groups become Teams that you can assign to projects.

Use JIT when profiles can be created at first sign-in. Use SCIM when your IdP needs to provision and remove access before or without a sign-in.

Assign roles through SCIM

In the current access model, Chromatic maps directory groups to account roles. Chromatic Support configures those mappings and the default account role for account collaborators who do not belong to a mapped group.

For project access, set a default project role and assign SCIM-synced Teams to projects. The default project role is the minimum role for every account collaborator. A Team can grant a higher role on each assigned project.

Some accounts configured before Teams use a role or roles attribute with owner, developer, reviewer, or viewer. This legacy setup assigns one project role across every project. Without a supported value, it assigns Developer. Follow the Teams migration guidance to move to the current model.

See Collaborators and roles for account and project role definitions.

Account and project access

• Profiles are automatically added to accounts that match their SSO subdomain at creation time.
• Project access comes from the account Admin role, a direct project assignment, the default project role, or Team membership.
• Role assignment via group mapping does not depend on email domain.
• If your account restricts sign-in by email domain or uses several domains, contact Chromatic Support to update the allow list.

SSO certificate

An SSO certificate is an X.509 certificate that your identity provider uses to sign SAML assertions or encrypt communication with Chromatic. It lets Chromatic verify that an authentication response came from your identity provider and was not changed in transit.

Change the SSO certificate

• Metadata URL: Provide a metadata URL from your IdP. Chromatic can fetch the new certificate automatically when it changes.

• Manual update: Send the new certificate to priority-support@chromatic.com with:

  • The requested change date, time, and timezone
  • A PEM-encoded X.509 certificate (accepted formats: .pem, .key, .crt, .cer, .cert)

Schedule a manual change during low-usage hours. Account collaborators may need to sign in again after the certificate rotates.

Frequently asked questions