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

# SSO troubleshooting

> Diagnose common sign-in failures across the WorkOS-backed SSO stack.

Most SSO issues fall into one of five categories. Match the symptom to the section, follow the checks in order, and contact [support@summand.com](mailto:support@summand.com) if nothing fits.

## Domain isn't routed to my IdP

**Symptom:** You enter your company email at `summand.com` but Summand asks for a password instead of redirecting to your IdP.

<Steps>
  <Step title="Confirm the domain is verified">
    **Settings → Organization → Domain Verification**. The domain you typed in the email field must show *Verified*. If it's *Pending*, re-check the DNS TXT record.
  </Step>

  <Step title="Confirm there's an active SSO connection">
    **Settings → Organization → Single Sign-On**. The connection state should be *Active*. *Draft* or *Inactive* means setup wasn't completed.
  </Step>

  <Step title="Check the email domain matches exactly">
    Subdomains aren't matched against parent domains. If you verified `acme.com` and the user signs in with `eng@labs.acme.com`, that's a different domain — verify it separately.
  </Step>
</Steps>

## "No SSO provider found for this email domain"

**Symptom:** Sign-in fails with this exact message before reaching the IdP.

This means `/api/auth/sso/check-domain` matched a verified domain in WorkOS but couldn't find a corresponding SSO connection on that organization. Either:

* The connection was deleted from the WorkOS portal but the domain is still registered, or
* The connection was set up for a different organization than the one the domain is on.

**Fix:** open the WorkOS Admin Portal (**Settings → Organization → Single Sign-On → Configure**) and confirm an active connection exists. If not, configure one.

## User reaches IdP but bounces back with an error

**Symptom:** The IdP authenticates the user (no errors at the IdP) but Summand shows *Sign-in failed* on return.

<Steps>
  <Step title="Check ACS / redirect URL exactness">
    The IdP's configured ACS URL or redirect URI must match what the WorkOS portal showed exactly — every character, every trailing slash. Re-paste from the portal.
  </Step>

  <Step title="Verify the SAML certificate is current">
    SAML certificates expire. The portal flags expired certs in **Single Sign-On → Connection details**. Renew via **Certificate Renewal → Configure** and re-upload from your IdP.
  </Step>

  <Step title="Confirm required attributes are sent">
    The SAML response (or OIDC ID token) must include `email` and either `name` or both `given_name` and `family_name`. Some IdPs default to omitting these unless you explicitly add them.
  </Step>

  <Step title="Check the user is assigned to the IdP application">
    For Okta, the user must be assigned to the SAML app under *Assignments*. For Entra, on *Users and groups*. For Google Workspace, the SAML app must be turned on for the user's OU.
  </Step>
</Steps>

## "Invalid SAML response" or "Bad assertion"

**Symptom:** The error message references the SAML response itself — invalid signature, untrusted certificate, schema mismatch.

<Steps>
  <Step title="Re-fetch IdP metadata">
    Click **Refresh metadata** on the connection in the WorkOS portal. If the metadata URL has rotated certificates, this picks up the new ones.
  </Step>

  <Step title="Confirm clock skew is reasonable">
    SAML responses include `NotBefore` and `NotOnOrAfter` timestamps. If your IdP's clock is far ahead/behind UTC, responses are rejected. WorkOS allows \~5 minutes of skew; clocks more than 5 minutes off need fixing on the IdP side.
  </Step>

  <Step title="Check NameID format">
    The IdP must return Name ID in `EmailAddress` format. Re-check the IdP's SAML configuration — it's the most commonly misconfigured field.
  </Step>
</Steps>

## Group → role mapping doesn't work

**Symptom:** SSO sign-in succeeds, but users land in Summand without the role you'd expect from their IdP group.

<Steps>
  <Step title="Confirm groups are in the assertion">
    Open the WorkOS Admin Portal → **Single Sign-On → Connection → Test Connection**. The test result shows the raw attributes WorkOS received. If `groups` isn't there, the IdP isn't sending it.
  </Step>

  <Step title="Check the group identifier format">
    Most issues here are Entra-specific — Entra emits group **Object IDs** (GUIDs) by default, not display names. Either configure Entra to emit `sAMAccountName`, or paste the GUIDs into the WorkOS portal mapping.
  </Step>

  <Step title="Re-authenticate after group changes">
    SAML group claims are sent at sign-in time. Adding a user to a group in your IdP doesn't update the claim until they sign in again. For real-time group propagation, use Directory Sync instead.
  </Step>
</Steps>

## Directory Sync isn't provisioning users

**Symptom:** Users added to a synced group in your IdP don't appear in Summand.

<Steps>
  <Step title="Confirm SCIM is configured and active">
    **Settings → Organization → Directory Sync** should show the connection as *Active*. If it's *Linked* but not *Active*, the SCIM provisioning step on the IdP side hasn't been enabled.
  </Step>

  <Step title="Check the SCIM endpoint and bearer token">
    From the WorkOS portal, regenerate the SCIM bearer token and re-paste it into the IdP. Common issue: the token was rotated in WorkOS and the IdP-side value drifted.
  </Step>

  <Step title="Check group filters in the IdP">
    Most IdPs require you to explicitly assign users *and* groups to the SCIM app. Just being in the IdP isn't enough — the SCIM scope is opt-in.
  </Step>

  <Step title="Inspect the SCIM activity log">
    The WorkOS portal's **Directory Sync** view shows recent SCIM events with success/failure status and the raw IdP payload. Failed events usually reveal a missing required attribute or a malformed group reference.
  </Step>
</Steps>

## When to escalate

If you've worked through the relevant section and still can't sign in:

1. From the WorkOS portal, run *Test Connection* and capture the full error text.
2. Note the user's IdP, browser, and the timestamp of the failed attempt.
3. Email [support@summand.com](mailto:support@summand.com) with all three. Enterprise customers also have a `#summand-support` channel — drop the same details there for faster escalation.