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

# Single Sign-On

> Let your team sign in to Overcut with your organization's identity provider (Okta, Microsoft Entra ID, Google Workspace, or any OIDC or SAML provider), and control who joins your workspace through it.

Enterprise single sign-on (SSO) connects an Overcut workspace to the identity
provider your organization already uses. Once connected, your team signs in
with **Continue with SSO** on the login page, and your workspace decides
whether new people from your email domain join automatically or only by
invitation.

Overcut supports both **OpenID Connect (OIDC)** and **SAML 2.0**. Okta,
Microsoft Entra ID, Google Workspace, and any other provider that speaks one
of these protocols work the same way.

<Info>
  SSO is connected by the Overcut team, not self-serve. You provide your
  provider's details and email domains, Overcut binds the provider to your
  workspace, and from then on workspace admins manage it under
  **Security → Single sign-on**. Contact your Overcut account team or use the
  **Ask to add SSO** button on that page to start.
</Info>

## How it works

1. A user opens the Overcut login page and chooses **Continue with SSO**.
2. They enter their work email. Overcut looks up the email domain and, if a
   workspace has SSO bound to that domain, sends them to your identity
   provider.
3. Your provider authenticates the user and returns their email, first name,
   and last name.
4. Overcut matches the email to an existing account. An existing member is
   signed in. A user with an open invitation gets an account and the
   invitation is consumed. Anyone else is admitted or rejected according to
   the workspace's auto-join setting (see [Who can join](#who-can-join)).

SSO users land in your existing workspace. They never get a personal
workspace of their own, and they skip the onboarding wizard.

<Note>
  If someone on your team already signs in with GitHub using the same email
  address, their first SSO login links to that existing account. They keep
  their workspace membership, roles, and history. Both sign-in methods keep
  working afterwards.
</Note>

## Who can join

A workspace with SSO has two membership modes, controlled by one toggle in the
provider's settings dialog:

| Mode                      | Toggle                                                   | Who gets in                                                                                                                                                            |
| ------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invitation only (default) | **Let anyone from these domains join automatically** off | Existing members and people with an open invitation. Anyone else who passes your identity provider is turned away with a message asking them to request an invitation. |
| Auto-join                 | **Let anyone from these domains join automatically** on  | Anyone who authenticates with your provider and has an email on one of the bound domains. They join as a regular member.                                               |

Auto-join is scoped to the email domains bound to your workspace. Overcut
never admits a user from a domain you did not register, whatever your
provider returns.

<Tip>
  Start in invitation-only mode for the verification login, then decide whether
  to switch on auto-join. You can change the toggle at any time; it applies to
  the next login.
</Tip>

## Choosing OIDC or SAML

Both protocols are fully supported and produce the same experience for your
users. Pick whichever matches your organization's standard.

|                        | OIDC                                                                     | SAML 2.0                                               |
| ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------ |
| What you send Overcut  | Issuer URL, client ID, client secret                                     | Identity provider metadata XML (or a metadata URL)     |
| What Overcut sends you | Redirect URI                                                             | Assertion Consumer Service (ACS) URL and SP entity ID  |
| Certificates to manage | None                                                                     | Your provider's signing certificate, rotated on expiry |
| Recommended when       | You have no strong preference. Simpler to configure and nothing expires. | Your security policy standardizes on SAML.             |

## Set up SSO

<Steps>
  <Step title="Tell Overcut your domains and protocol" icon="user">
    Send your Overcut account team:

    * The email domain or domains your users sign in with (for example
      `acme.com` and `acme.io`). Only domains your organization owns can be
      bound. Public mailbox domains such as `gmail.com` are refused.
    * Whether you will use OIDC or SAML.
    * The workspace to connect. Only one workspace can be bound to a given
      domain.

    Overcut replies with a provider alias for your organization. The alias
    appears in the URLs below as `<alias>`.
  </Step>

  <Step title="Create the application in your identity provider" icon="key">
    **OIDC**

    Create a web application (in Okta: **Applications → Create App Integration → OIDC - OpenID Connect → Web Application**) with:

    | Setting              | Value                                                            |
    | -------------------- | ---------------------------------------------------------------- |
    | Sign-in redirect URI | `https://auth.overcut.ai/realms/overcut/broker/<alias>/endpoint` |
    | Grant type           | Authorization Code                                               |
    | Scopes               | `openid`, `profile`, `email`                                     |

    Assign the users or groups who should be able to sign in, then send
    Overcut the **issuer URL**, **client ID**, and **client secret**. Share
    the secret through a secure channel, never in a ticket or chat message.

    **SAML 2.0**

    Create a SAML application (in Okta: **Applications → Create App Integration → SAML 2.0**) with:

    | Setting                        | Value                                                            |
    | ------------------------------ | ---------------------------------------------------------------- |
    | Single sign-on URL (ACS URL)   | `https://auth.overcut.ai/realms/overcut/broker/<alias>/endpoint` |
    | Audience URI (SP entity ID)    | `https://auth.overcut.ai/realms/overcut`                         |
    | Name ID format                 | `EmailAddress`                                                   |
    | Application username           | Email                                                            |
    | Response and assertion signing | Signed                                                           |

    Add these attribute statements:

    | Attribute name | Value                    |
    | -------------- | ------------------------ |
    | `email`        | The user's email address |
    | `firstName`    | The user's first name    |
    | `lastName`     | The user's last name     |

    Assign the users or groups who should be able to sign in, then send
    Overcut the **identity provider metadata** (the XML file or its URL).
    Overcut's SP metadata is available at
    `https://auth.overcut.ai/realms/overcut/broker/<alias>/endpoint/descriptor`
    once the provider is connected, if your provider asks for it.
  </Step>

  <Step title="Overcut connects the provider" icon="link">
    Overcut registers your provider and binds it to your workspace and
    domains. The provider then appears under **Security → Single sign-on** in
    your workspace, in invitation-only mode.
  </Step>

  <Step title="Verify with one user" icon="user-check">
    Invite one person from your organization to the workspace, then have them
    sign in through **Continue with SSO**. They should land in your workspace
    as a member, with the invitation consumed. Signing in a second time should
    take them straight in.
  </Step>

  <Step title="Roll out to the team" icon="users">
    Either invite the rest of your team, or open the provider's settings and
    switch on **Let anyone from these domains join automatically** so anyone
    on your domains can sign in without an invitation.
  </Step>
</Steps>

## Manage SSO in your workspace

Open the workspace, then go to **Security → Single sign-on**. The page lists
every provider bound to the workspace with its display name and bound domains,
plus a **Disabled** or **Auto-join** tag where those apply.

Select the pencil icon on a provider to open its settings dialog:

* **Membership**: the **Let anyone from these domains join automatically**
  toggle switches between invitation-only and auto-join (see
  [Who can join](#who-can-join)).
* **Status**: the **Enabled** toggle turns SSO on or off for this provider.
  While disabled, users who choose **Continue with SSO** are told that
  single sign-on is not enabled for their identity provider. Existing members
  can still sign in with any other method they have, such as GitHub.

Changing these settings requires the workspace settings permission. Users
without it see the page read-only.

Adding domains, changing the provider's configuration, rotating an OIDC client
secret, or replacing a SAML certificate all go through the Overcut team. Reach
out with the new details and Overcut applies them.

## Signing in with SSO

On the login page, choose **Continue with SSO**, enter your work email, and
select **Continue**. You are redirected to your organization's identity
provider, and back to Overcut once it confirms who you are.

<AccordionGroup>
  <Accordion title="No single sign-on is configured for this email domain">
    The domain of the email you entered is not bound to any workspace. Check
    for a typo, or sign in with GitHub instead. If your organization should
    have SSO, ask your workspace admin to confirm which domains are bound.
  </Accordion>

  <Accordion title="Your organization uses single sign-on, but your email has not been invited to the workspace yet">
    Your identity provider accepted you, but the workspace is in
    invitation-only mode and there is no open invitation for your email. Ask a
    workspace admin to invite you, or to switch on auto-join.
  </Accordion>

  <Accordion title="Single sign-on is not enabled for this identity provider">
    A workspace admin has switched the provider's **Enabled** toggle off. Sign
    in another way, or ask an admin to re-enable it.
  </Accordion>

  <Accordion title="Your identity provider shows an error">
    The application on your provider's side is misconfigured or you are not
    assigned to it. Common causes: the redirect or ACS URL does not match the
    one Overcut gave you, the application is not assigned to your user or
    group, or a SAML certificate has expired. Your identity provider admin can
    check the application's sign-in log.
  </Accordion>
</AccordionGroup>

## Limitations

* **Overcut Cloud only.** Customer-managed deployments configure SSO in their
  own identity setup; this page does not apply to them.
* **No single logout.** Signing out of Overcut ends your Overcut session but
  does not sign you out of your identity provider.
* **One workspace per domain.** A given email domain can be bound to a single
  workspace.

## Related

* [Privacy and Security](/docs/privacy-and-security): how Overcut protects
  workspace data and secrets.
* [Audit Trail](/docs/reference/audit-trail): who changed what in your
  workspace, including SSO settings.
* [Workspace Settings](/docs/reference/workspace-settings): the rest of the
  workspace-level configuration.