Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Set Up Organization-Level SSO

Organization-level Single Sign-On (SSO) lets your team sign in to Coalesce through your identity provider with a single connection. You set it up yourself from Organization Settings using a guided setup assistant, and Coalesce never sees your identity provider credentials.

This replaces the older per-product SSO form. If your organization already uses SSO, see Moving From Legacy SSO before you start.

Already Use SSO for Catalog or Quality?

If your organization already signs in to Coalesce Catalog or Coalesce Quality with SSO, and they're in the same region as Transform, you can reuse that connection instead of creating a new one. Contact Coalesce Support to set it up.

Before You Begin​

  • Permissions: You must be an Org Admin. Other users can view the page, but the controls are disabled.
  • Identity provider access: You need administrator access to your identity provider, such as Okta, Microsoft Entra ID, or Google Workspace. You'll create or update an application there during setup.
  • User email addresses: Coalesce matches each person to their Coalesce user by email address. Every user who signs in with SSO must have an email address in their identity provider profile. Users without one can't sign in.
  • Products in more than one region: A connection covers the Coalesce products your organization uses in one region. Products in other regions keep their own sign-in, and setting up SSO for Transform doesn't change them.
  • Pop-ups and new tabs: The setup assistant opens in a new browser tab. Allow new tabs for Coalesce if your browser blocks them.
  • A break-glass administrator: Make sure at least one Org Admin can sign in with an email address and password. See Keep a Break-Glass Administrator.

Keep a Break-Glass Administrator​

Keep at least one Org Admin who signs in with an email address and password instead of SSO. If your SSO connection stops working, this account is how you get back in to fix it.

  • Use a team mailbox, not a person's address, so the account survives staff changes.
  • Store the password in your company's password vault and limit who can use it.
  • Don't use it for daily work, scheduled jobs, or API tokens.
  • Test it in a private window before you turn on the new sign-in experience, and keep it afterwards for identity provider outages.
  • If you disable password users to require SSO, leave this one active.

If your organization already uses SSO and has no password users, an Org Admin can create one:

  1. Go to Org Settings > Users and select Add New User.
  2. In the Add User window, enter a first name, last name, and the team mailbox address as the email.
  3. Turn on Set User Password, then enter a password. If you leave it off, Coalesce emails the mailbox a link to set the password instead.
  4. Under Role, select Org Admin, then select Add User.
  5. Sign in as that user in a private window to confirm it works.

Step 1: Set Your Sign-In URL​

Your sign-in URL is the address your team uses to sign in with SSO, such as https://acme.app.coalescesoftware.io. You must save a sign-in URL before you can add an SSO connection.

  1. Go to Organization Settings > Single Sign-On.
  2. Under Sign-in URL, enter your subdomain. This is usually your company name, such as acme.
  3. Select Save. The page shows the full address your users will sign in at.

Subdomains can contain only letters, numbers, and dashes. Some names are reserved and can't be used. You can change your sign-in URL later, but let your users know first, and update any bookmarks or allow lists that use the old address.

Check With Your IT Team

Some organizations allowlist sign-in URLs in their identity provider or network. Agree on the subdomain with your IT team before you save it.

Step 2: Add an SSO Connection​

A connection links your Coalesce organization to one identity provider. You can add more than one connection, for example during a move from one provider to another.

  1. Under Enterprise connections, select Set up SSO. If your organization already has a connection, select Add connection instead.
  2. Review the Add SSO connection window. It shows your organization and sign-in URL.
  3. Select Open Auth0 setup. The setup assistant opens in a new tab. Keep the Coalesce tab open.
  4. In the setup assistant, choose your identity provider and follow its steps. The assistant walks you through creating the application in your identity provider and entering its details.
  5. When the assistant finishes, go back to the Coalesce tab and reload the page.
Control Access in Your Identity Provider

Anyone your identity provider lets into the Coalesce application can sign in. Coalesce creates them as an Org Member with no Project access the first time they sign in. Control who gets in by assigning users and groups to the application in your identity provider. If you're moving from legacy SSO, assign the same users and groups as your legacy application.

While you're working in the assistant, the connection appears as New connection with the status Setup in progress. After you reload the page and the connection is live, it shows your identity provider's name and the status Enabled.

The setup assistant supports common identity providers, including:

  • Okta
  • Microsoft Entra ID
  • Google Workspace
  • Any SAML or OpenID Connect provider

Each time you start a setup, Coalesce creates a new setup link for the assistant. Once the assistant opens, you have five hours to finish. If you close the assistant or run out of time, start again from the connection row.

From the connection row, you can:

  • Restart connection setup: Open the assistant with a new setup link. The setup starts from the beginning, and any assistant tab you opened earlier stops working.
  • Cancel: Stop the setup and remove the in-progress connection.

You can only have one setup in progress at a time. Finish or cancel it before you add or reconfigure another connection.

Step 3: Turn On the New Sign-In Experience​

This step applies only if your organization has a legacy SSO setup. Organizations without one are already on the new sign-in experience and can skip to Step 4.

Adding a connection doesn't switch your users over by itself. Your legacy SSO keeps working until you turn on the new sign-in experience. The switch is enabled only after at least one connection is set up.

The switch applies to everyone in your organization, not only SSO users. Once it's on, every user sees the new sign-in page the next time they sign in, so the test in Step 4 runs live for everyone. Users who sign in with an email and password, including your break-glass administrator, reset their password the first time they see the new sign-in page. See How to Reset Your Password. Turn the switch on during a quiet period, such as outside business hours, and let your users know ahead of time.

Make Sure You Have a Way Back In

Before you turn on the switch, confirm that your break-glass administrator can sign in to Coalesce with an email address and password, and that someone can open its mailbox to reset the password on the new sign-in page. If the new connection doesn't work and your SSO session ends, that administrator can sign in and turn the switch back off.

  1. Under New sign-in experience, turn the switch on.
  2. Don't reload or close this tab. Your current session came through the legacy sign-in experience, so reloading the page signs you out.
  3. Test your new connection in Step 4 while this tab stays open.

If the test fails, go back to this tab and turn the switch off. That restores the legacy sign-in experience while you troubleshoot.

Step 4: Test Sign-In​

Confirm the connection works before you move your whole team over. Test in a separate private window so your current session stays intact.

  1. Open a private or incognito browser window.
  2. Go to your sign-in URL.
  3. Select your connection and sign in with your identity provider account.

If your organization has more than one connection, the sign-in page shows one button for each. Users pick the one that matches their identity provider. Coalesce doesn't route people to a connection based on their email domain.

If sign-in works, your setup is done. If your organization is moving from legacy SSO, you can now close or reload your original tab and sign in again with the new connection.

Reconfigure a Connection​

To change the settings of a live connection, such as a certificate or client secret, select Reconfigure on its row. The setup assistant opens in a new tab with that connection's settings.

To remove a live connection, contact Coalesce Support.

Moving From Legacy SSO​

If your organization set up SSO before organization-level SSO was available, your existing setup appears in the Legacy SSO Setup section of the Single Sign-On page. A banner at the top of the page reminds you to move over.

Legacy SSO Ends December 15, 2026​

Legacy SSO connections stop working on December 15, 2026. Until then, you can turn off the new sign-in experience to go back to your legacy setup. After that date, users can only sign in with SSO through an organization-level connection.

Move to Organization-Level SSO​

  1. Confirm that your break-glass administrator can sign in with an email address and password.
  2. Make sure every user has an email address in your identity provider. See Microsoft Entra ID Users if you use Entra.
  3. Complete Step 1 and Step 2 above. Your legacy setup keeps working while you do this.
  4. Turn on the new sign-in experience and, without reloading that tab, test sign-in in a private window.

After you turn it on:

  • The legacy form becomes read-only.
  • Everyone in your organization sees the new sign-in page. Users who sign in with an email and password reset their password the first time they see it.
  • Existing users are linked to their Coalesce user by email address the next time they sign in. Their Projects, Workspaces, roles, and saved credentials don't change.
  • Existing API tokens keep working, so scheduled jobs and integrations that use the API or the Coalesce CLI don't need new tokens.
  • If you allowlist sign-in URLs anywhere, update them to your new sign-in URL.

Microsoft Entra ID Users​

Coalesce needs an email address for every user, and some Microsoft Entra ID profiles don't have one set. Anyone without an email address in their Entra profile can't sign in after you turn on the new sign-in experience.

Coalesce only reads profile changes when a user signs in. Before you switch over:

  1. In the Microsoft Entra admin center, go to Users, open each Coalesce user, and select Properties. Under Contact information, make sure Email is set. This is the user's mail attribute, which Entra sends to Coalesce as the email claim. The User principal name isn't used, even if it looks like an email address.
  2. Ask each of those users to sign in to Coalesce at least once so Coalesce picks up the change.

If some active users don't have an email address, the Single Sign-On page shows a warning with the number of affected users. To find them, go to Org Settings > Users and search the Email column for MISSING. Affected users show <MISSING EMAIL>, or a blank email address, in place of an email address.

Troubleshooting​

The Set Up SSO Button Is Disabled​

Save a sign-in URL first. See Step 1. If the button is still disabled, check that you're an Org Admin, or that no other connection setup is in progress.

The Connection Still Shows Setup in Progress​

Coalesce checks your connections when the page loads. Reload the page after you finish in the setup assistant. If it still shows Setup in progress, select Restart connection setup and complete every step in the assistant.

The assistant has a five-hour limit once it opens. Select Restart connection setup on the connection row to get a new link, then complete the setup in one session.

A User Signs In but Has the Wrong Permissions or Is Missing Credentials​

If a user can sign in with SSO but has lost their Project access or roles, or their saved warehouse or Git credentials are gone, Coalesce probably created a new user record for them instead of linking their existing one. This happens when the email address from your identity provider doesn't exactly match the one on their Coalesce user, including capitalization. A new record starts as an Org Member with no Project access and no saved credentials.

  1. Go to Org Settings > Users and look for two records with the same person's email address.
  2. Contact Coalesce Support to link the user's original record. Include the user's email address and your organization ID.
  3. If you'd rather keep the new record, assign it the same roles as the original, ask the user to re-enter their credentials, and then disable the original record.

To stop this happening to other users, make each email address in your identity provider match the user's Coalesce email address exactly before they next sign in.

A User Can't Sign In After the Switch​

Check that the user has an email address in your identity provider profile and that it matches their Coalesce email address. If needed, turn off the new sign-in experience to restore legacy sign-in while you fix the issue. If you can't sign in with SSO to do that, sign in as an administrator with an email address and password, or contact Coalesce Support. See also Common SSO Errors.

What's Next?​