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

# SSO Troubleshooting

> Common issues connecting an identity provider to Quippy.

<AccordionGroup>
  <Accordion title="Test connection says 'IdP unreachable' or times out">
    The **Test connection** button fetches your IdP's discovery document
    (OIDC) or metadata (SAML) with a 10-second timeout. If that times out:

    * For **OIDC** — confirm the issuer URL is exactly right and that
      `{issuer}/.well-known/openid-configuration` returns `200` from a public
      network. Some IdPs serve discovery only on a specific authorization
      server path (e.g. `/oauth2/default`), not the root.
    * For **SAML** — confirm your **IdP Entry Point** is the metadata URL
      (often ending in `/metadata` or `/FederationMetadata`) and that it
      returns XML.
    * If your IdP sits behind an allowlist, add Quippy's outbound IPs (ask
      your account contact) before retesting.
  </Accordion>

  <Accordion title="Sign-in redirects to the IdP, then loops back to the Quippy login page">
    Usually a group- or provisioning-mismatch:

    * If **Auto-create users on first sign-in** is off, the user must
      already exist in your institution's member list. Add them via the
      Members page first.
    * If it's on and the user still can't sign in, check your IdP actually
      releases an email claim — most IdPs require this to be enabled per-app.
  </Accordion>

  <Accordion title="Signature validation failed / invalid token">
    For SAML — the **Signing Certificate** you pasted doesn't match the
    cert your IdP is signing with. Download the current cert from the IdP,
    paste it fresh (including `-----BEGIN CERTIFICATE-----` and the matching
    `END` line), and save.

    For OIDC — the issuer URL you pasted doesn't match the `iss` claim in
    the token. Most common: you used the tenant root URL instead of the
    authorization-server-specific URL.
  </Accordion>

  <Accordion title="Users sign in but end up with the wrong role">
    Open **Provisioning → Group → role mapping** on the SSO page. Either:

    * Your **Default role** is applied because none of the group mappings
      matched — check what group claim your IdP is actually sending (logs on
      the IdP side help).
    * The group claim value on the IdP side changed — map the new value,
      re-test, and ask the user to sign in again.
  </Accordion>

  <Accordion title="I enabled SSO and got locked out of the admin portal">
    This is exactly why the [Set up SSO](/sso/setup#step-5) page warns
    against removing your local password-authenticated admin before the
    first successful SSO sign-in. If it's happened anyway, contact your
    Quippy account manager — we can roll back the `enabled` flag for your
    institution so you can fix the configuration and re-test.
  </Accordion>
</AccordionGroup>

Still stuck? Grab:

* The **institution slug** you're signing in with
* The **protocol** you picked (OIDC or SAML)
* A screenshot of the **Test connection** output
* The approximate time (UTC) of a failing sign-in attempt

…and send them with your support ticket.