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

# Single Sign-On (SSO)

> Connect your identity provider so your team signs in to Coalesce Quality with your organization’s credentials

Single Sign-On (SSO) lets your team sign in to Coalesce Quality using your organization’s identity provider (IdP) — such as Microsoft Entra ID (Azure AD), Okta, Google Workspace, or any provider that supports SAML 2.0 or OpenID Connect (OIDC). Authentication is handled by your IdP, so users never need a separate Coalesce Quality password, and you keep central control over access, password policy, and offboarding.

<Note>
  SSO is an enterprise feature. Connections are set up together with our team — reach out to your Coalesce contact or email [support@synq.io](mailto:support@synq.io) to start.
</Note>

## How SSO works at Coalesce

Coalesce Quality uses [Auth0](https://auth0.com/docs/authenticate/enterprise-connections) as its authentication layer. Setting up SSO is a short, guided exchange between you and our team:

<Steps>
  <Step title="Create an app in your identity provider">
    Register Coalesce Quality as an application (sometimes called an “enterprise app”, “integration”, or “relying party”) in your IdP.
  </Step>

  <Step title="Exchange connection details">
    We give you the Coalesce Quality URL to add to your app, and you send us your app’s connection details in return.
  </Step>

  <Step title="We configure the connection">
    Our team creates the enterprise connection on the Coalesce Quality side and links it to your workspace.
  </Step>

  <Step title="Test and enforce">
    You verify a test login, then we enable SSO for your workspace.
  </Step>
</Steps>

## Before you begin

* **Administrator access to your identity provider** — you need to be able to create applications and assign users in your IdP.
* **An enterprise plan** with SSO enabled. Contact your Coalesce account team if you’re unsure whether it’s enabled.
* **Your region** — Coalesce Quality is deployed in two regions. Note which one your workspace uses: when you register an OAuth/OIDC app you’ll enter its **callback URL** as the redirect URI. (For SAML connections, Coalesce gives you a connection-specific ACS URL based on this.)

  | Region           | App URL                  | Callback URL                                       |
  | ---------------- | ------------------------ | -------------------------------------------------- |
  | **EU** (default) | `https://app.synq.io`    | `https://teamcoalesce.eu.auth0.com/login/callback` |
  | **US**           | `https://app.us.synq.io` | `https://teamcoalesce.us.auth0.com/login/callback` |

## Step 1: Connect your identity provider

Select your identity provider below and follow its instructions end to end. Each one lists what you’ll need, the steps to perform in your IdP, and what to send back to us. The generic **SAML 2.0** and **OIDC** tabs cover any provider not listed — including Ping Identity, ADFS, OneLogin, and JumpCloud (see [Other identity providers](#other-identity-providers)).

<Tabs>
  <Tab title="Microsoft Entra ID (Azure AD)">
    **What you need:** the [**Redirect URI**](#before-you-begin) for your region.

    **Steps:**

    1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **Identity → Applications → App registrations → New registration**.
    2. Give it a name, choose the supported account types for your organization, and add the **Redirect URI** (platform **Web**) for your region.
    3. Under **Certificates & secrets**, create a new **client secret** and copy its value immediately — it can’t be viewed again later.
    4. Under **API permissions**, make sure **User.Read** is granted and grant admin consent. Add **Directory.Read.All** only if you need group or extended attributes.
    5. Assign the users or groups who should have access.

    **What you send:**

    * **Application (client) ID**
    * **Client secret**
    * Your **Microsoft Entra (Azure AD) domain**
  </Tab>

  <Tab title="Okta">
    **What you need:** the [**Sign-in redirect URI**](#before-you-begin) for your region.

    **Steps:**

    1. In the Okta Admin Console, go to **Applications → Applications → Create App Integration**.
    2. Select **OIDC – OpenID Connect** and **Web Application**, then click **Next**.
    3. Add the **Sign-in redirect URI** for your region.
    4. Under the **Assignments** tab, assign the users or groups who should have access.
    5. Save the app, then copy its **Client ID** and **Client secret**.

    **What you send:**

    * **Client ID**
    * **Client secret**
    * Your **Okta domain** (`https://<your-org>.okta.com`)
  </Tab>

  <Tab title="Google Workspace">
    **What you need:** the [**Authorized redirect URI**](#before-you-begin) for your region.

    **Steps:**

    1. In the [Google Cloud Console](https://console.cloud.google.com), configure the **OAuth consent screen** for your organization (User type **Internal**).
    2. Go to **APIs & Services → Credentials → Create credentials → OAuth client ID** and choose **Web application**.
    3. Add the **Authorized redirect URI** for your region.
    4. Create the client, then copy its **Client ID** and **Client secret**.

    **What you send:**

    * **Client ID**
    * **Client secret**
    * Your **Google Workspace domain**
  </Tab>

  <Tab title="SAML 2.0 (other)">
    For any IdP that supports SAML 2.0.

    **What you need:** the **ACS URL** and **SP Entity ID / Audience** for your connection — Coalesce provides both.

    **Steps:**

    1. Create a new SAML application / relying party for Coalesce Quality.
    2. Set the **Assertion Consumer Service (ACS) URL** and **SP Entity ID / Audience** to the values Coalesce provides. The ACS URL is your region’s callback URL with a `?connection=` parameter, and the Audience is a `urn:auth0:...` identifier.
    3. Configure the assertion to send the user’s email (as the Name ID or an attribute) and name (see [Map user attributes](#step-2-map-user-attributes)).
    4. Assign the relevant users or groups.

    **What you send:**

    * The IdP **SAML metadata XML** (or metadata URL) — this includes the IdP Entity ID / Issuer, the SSO endpoint URL, and the X.509 signing certificate
    * If you can’t share metadata, send those three values individually
  </Tab>

  <Tab title="OIDC (other)">
    For any IdP that supports OpenID Connect.

    **What you need:** the [**Redirect URL**](#before-you-begin).

    **Steps:**

    1. Register a new OIDC / OAuth 2.0 application for Coalesce Quality.
    2. Set the **Redirect URL** to the callback URL for your region.
    3. Enable the `openid`, `profile`, and `email` scopes (this sends the email and name; see [Map user attributes](#step-2-map-user-attributes)).
    4. Assign the relevant users or groups.

    **What you send:**

    * **Client ID**
    * **Client secret**
    * **Issuer URL** (the OIDC discovery base, e.g. `https://your-idp.example.com`)
  </Tab>
</Tabs>

<Warning>
  Send the **client secret** over a secure channel — a secrets manager, or a 1Password shared item or one-time link — never plain email or chat. The client ID, domain, and SAML metadata aren’t sensitive and can be shared normally.
</Warning>

## Step 2: Map user attributes

Coalesce Quality identifies users by their email address and uses their name for display. Make sure your IdP sends these claims:

| Attribute | Required    | Notes                                                                                                |
| --------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| **Email** | Yes         | Used as the unique user identifier. For SAML, this is typically the Name ID or an `email` attribute. |
| **Name**  | Recommended | Used for display. Send a full name, or first name and last name.                                     |

For OIDC, requesting the `openid`, `profile`, and `email` scopes covers these claims.

## Step 3: Test and enforce SSO

1. Once we’ve configured the connection, we share a test login link (or you sign in from the configured app).
2. Confirm you’re redirected to your IdP, authenticate, and land in your Coalesce Quality workspace.
3. When the test succeeds, we enable SSO for your workspace.

<Warning>
  Test with a real account from your IdP before rolling SSO out to your whole team. If attribute mapping is wrong, sign-in will fail or create users with missing details.
</Warning>

## User provisioning and roles

New users are provisioned automatically the first time they sign in through SSO (just-in-time provisioning). A newly provisioned user is assigned the **Business User** role, which has the most limited permissions — see [User roles](/admin/user_roles) for what each role can do.

<Note>
  We recommend [inviting users](/admin/invite_user) through the app UI and assigning their role **before** they sign in for the first time. Otherwise they land with the limited permissions of a Business User until an admin updates their role on the [Team page](https://app.synq.io/settings/team).
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sign-in fails or loops back to the login screen">
    Usually the URL you entered in your IdP doesn’t exactly match the one Coalesce provided. Re-check it for your region and that there are no trailing spaces.
  </Accordion>

  <Accordion title="Sign-in worked before but suddenly stopped">
    For OAuth/OIDC connections (Entra ID, Okta, Google Workspace), the **client secret** has likely expired — Microsoft Entra secrets expire by default. Generate a new client secret in your IdP and send the new value to Coalesce.
  </Accordion>

  <Accordion title="“Invalid signature” or certificate errors (SAML connections)">
    The X.509 signing certificate Coalesce has doesn’t match the one your IdP is using — often after a certificate rotation. Send us your updated metadata so we can refresh the connection.
  </Accordion>

  <Accordion title="User signs in but has no name or the wrong email">
    Check your attribute / claim mapping in [Map user attributes](#step-2-map-user-attributes). The email claim must be present and must be the address you expect to identify the user by.
  </Accordion>

  <Accordion title="Wrong region">
    Make sure the URLs and identifier you entered match your workspace’s region (`app.synq.io` for EU, `app.us.synq.io` for US). Values from the other region won’t work.
  </Accordion>
</AccordionGroup>

## Other identity providers

Coalesce Quality works with any identity provider that supports SAML 2.0 or OpenID Connect, even if it isn’t listed in [Step 1](#step-1-connect-your-identity-provider):

* **Ping Identity (PingOne / PingFederate)** and **ADFS** — both support SAML 2.0 and OIDC. Create the application in your provider and follow the generic **SAML 2.0 (other)** or **OIDC (other)** instructions in [Step 1](#step-1-connect-your-identity-provider).
* **On-premises Active Directory / LDAP** — supported, but requires additional setup beyond the standard cloud flow. Contact [support@synq.io](mailto:support@synq.io) to connect an on-premises directory.

If you’re not sure whether your provider is supported, reach out to [support@synq.io](mailto:support@synq.io).