> ## 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.

# Set up SSO

> Step-by-step walkthrough for connecting your identity provider to Quippy.

About **15 minutes**. No code deploy required. You can switch between OIDC
and SAML at any time before you flip **Enable SSO for this institution**.

<Steps>
  <Step title="Sign in to the Admin Portal">
    Go to [business.quippy-lab.com](https://business.quippy-lab.com) and sign in
    with the admin account your Quippy contact provisioned for you.

    * **Institution slug** — a short identifier for your organization (e.g.
      `acme-corp`). Your Quippy contact will have given you this.
    * **First-time sign-in** — you'll be asked to change the password.
    * **Admins only** — the portal accepts institution administrators.
      Regular users sign in at the main app, not here.

    Once inside, open **Single Sign-On** from the sidebar. You should see a
    form with cards for **Endpoints for your IdP**, **Protocol & routing**,
    the protocol-specific config, and **Provisioning**.

    <Frame>Admin portal SSO page — screenshot placeholder.</Frame>
  </Step>

  <Step title="Choose OIDC or SAML, then fill in your IdP details">
    In the **Protocol & routing** card, toggle between **OIDC** and **SAML 2.0**.
    Then fill in the protocol-specific card that appears below.

    <Tabs>
      <Tab title="OIDC">
        In the **OIDC configuration** card:

        | Field             | What to paste                                                                      |
        | ----------------- | ---------------------------------------------------------------------------------- |
        | **Issuer URL**    | The base URL of your OIDC issuer. Must expose `/.well-known/openid-configuration`. |
        | **Client ID**     | The client ID from the app you create in your IdP.                                 |
        | **Client Secret** | The client secret from the same app. Encrypted at rest, never echoed back.         |

        Scopes default to `openid`, `profile`, and `email`. You don't need to
        change them for standard setups.
      </Tab>

      <Tab title="SAML 2.0">
        In the **SAML 2.0 configuration** card:

        | Field                   | What to paste                                                                                             |
        | ----------------------- | --------------------------------------------------------------------------------------------------------- |
        | **IdP Entry Point**     | The single sign-on URL from your IdP's SAML app.                                                          |
        | **IdP Entity ID**       | The issuer / entity ID the IdP will use to sign assertions.                                               |
        | **Signing Certificate** | The IdP's public signing cert, PEM-encoded (`-----BEGIN CERTIFICATE-----` … `-----END CERTIFICATE-----`). |
        | **Signature Algorithm** | `SHA-256` (default) or `SHA-512`. Match whatever your IdP is configured to sign with.                     |
      </Tab>
    </Tabs>
  </Step>

  <Step title="Copy Quippy's endpoints into your IdP">
    The **Endpoints for your IdP** card shows four URLs generated for your
    institution. Copy the ones your IdP asks for into its application config.

    | Quippy label          | Where it goes in your IdP               |
    | --------------------- | --------------------------------------- |
    | **OIDC Redirect URL** | "Sign-in redirect URI" / "Callback URL" |
    | **SAML ACS URL**      | "Assertion Consumer Service" URL        |
    | **SAML Entity ID**    | "Audience URI" / "SP Entity ID"         |
    | **SAML Metadata URL** | For IdPs that import SP metadata by URL |

    All four have the shape
    `https://api.quippy-lab.com/api/v2/sso/{oidc|saml}/<your-slug>/...` so you
    can sanity-check that the slug matches your institution.

    <Note>
      Paste only the URLs your chosen protocol needs. OIDC setups only use
      the **OIDC Redirect URL**; SAML setups use the three SAML URLs.
    </Note>
  </Step>

  <Step title="Set email domains and group → role mapping">
    In **Protocol & routing**, add the **Email domains** your employees use —
    e.g. `acme.com`, `acme.co.uk`. When someone enters `jane@acme.com` on the
    login page, Quippy will send them to your IdP instead of prompting for a
    password.

    In **Provisioning**, configure:

    * **Auto-create users on first sign-in** — when on, Quippy creates the
      user record the first time they sign in via your IdP. When off, only
      pre-existing members can sign in with SSO.
    * **Default role** — applied when an IdP group claim doesn't match any
      mapping. Valid roles: `admin`, `manager`, `editor`, `member`, `viewer`.
    * **Group → role mapping** — map IdP group claim values to Quippy roles.
      For example, `quippy-admins → admin`, `quippy-managers → manager`.
  </Step>

  <Step title="Test, then enable">
    Click **Test connection**. Quippy will:

    * For OIDC — fetch `{issuer}/.well-known/openid-configuration` (10-second
      timeout) and report the discovered `authorization_endpoint`,
      `token_endpoint`, `jwks_uri`, and PKCE support.
    * For SAML — fetch your **IdP Entry Point** and confirm the response
      looks like SAML metadata (contains `EntityDescriptor` or
      `IDPSSODescriptor`).

    Fix any errors the test surfaces — typically a wrong issuer URL, a cert
    that doesn't match, or an unreachable endpoint — then click **Save**.

    Once the test passes, tick **Enable SSO for this institution** and save
    again.

    <Warning>
      **Keep a backup admin.** Do **not** remove existing
      password-authenticated admin accounts from Quippy until your first SSO
      sign-in has completed end-to-end. That local admin is your escape hatch
      if the IdP config turns out to be wrong — otherwise a bad cert or the
      wrong issuer URL will lock everyone out.
    </Warning>
  </Step>
</Steps>

## Next

* Per-IdP cheat sheets: [Okta](/sso/okta), [Entra](/sso/entra),
  [Google Workspace](/sso/google-workspace), [OneLogin](/sso/onelogin)
* Stuck on a test failure? See [SSO Troubleshooting](/sso/troubleshooting).