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

# Set up workspace single sign-on (SSO)

> Connect Okta, Microsoft Entra ID, Auth0, or any OIDC or SAML 2.0 provider so your team signs in to Vibely with company credentials.

Single sign-on (SSO) lets your team sign in to Vibely with the same company account they use everywhere else, and lets your identity provider (IdP) decide who gets in.

<Frame>
  <img src="https://cdn.vibely.sh/doc/v1/workspace-sso.webp" alt="Set up workspace single sign-on (SSO)" width="1200" height="675" />
</Frame>

SSO is available on the **Business** plan. The workspace owner or an admin sets it up.

<Note>
  This page covers SSO for your team's access to **Vibely itself**. To add sign-in to an app you build, see [Authentication](/features/backend/auth).
</Note>

Sign-in always starts from Vibely: your team enters their work email on the Vibely sign-in page and is sent to your IdP. Starting from a tile in your IdP's dashboard isn't supported.

## Supported SSO protocols

| | OIDC | SAML 2.0 |
| - | - | - |
| Setup | Self-serve | Needs Vibely support to register your IdP |
| You give Vibely | Issuer URL, client ID, client secret | A provider ID |
| You give your IdP | Vibely's redirect URI | Vibely's ACS URL and entity ID |

* **OpenID Connect (OIDC)** is recommended. You can set it up end to end yourself.
* **SAML 2.0** works with any SAML IdP. Your IdP's metadata has to be registered with Vibely's sign-in service first, which support does for you.

<Warning>
  There's no Vibely app in the Okta or Microsoft Entra gallery. Every setup below uses a custom application.
</Warning>

## Prerequisites

* Admin access to your IdP (Okta, Microsoft Entra ID, Auth0, or another provider).
* The owner or admin role in a **Business** workspace.
* A **verified domain**. See [Verify your domain](/features/workspace/identity#verify-your-domain).

## Start SSO setup in Vibely

<Steps>
  <Step title="Open Identity">
    Go to **Settings → Access → Identity**.
  </Step>

  <Step title="Verify your domain">
    Under **Domain verification**, confirm the status is **Verified**.
  </Step>

  <Step title="Choose a protocol">
    Under **Single sign-on**, pick **OIDC** or **SAML 2.0** in **Protocol**. The fields change to match.
  </Step>

  <Step title="Configure your IdP">
    Copy the values Vibely shows into your IdP. See the reference below and the guide for your provider.
  </Step>

  <Step title="Enter your IdP's details">
    For OIDC, paste the issuer URL, client ID, and client secret. For SAML, paste the provider ID.
  </Step>

  <Step title="Turn it on">
    Turn on **Enable SSO** and click **Save single sign-on**.
  </Step>

  <Step title="Set the join role">
    Under **User provisioning**, set **Role on first SSO login**. Start with **Viewer** if you're unsure.
  </Step>
</Steps>

### IdP configuration reference

<Tabs>
  <Tab title="OIDC">
    * Application type: web application (a confidential client with a client secret)
    * Grant type: `Authorization Code`, with PKCE (`S256`)
    * Redirect URI: `https://vibely.sh/api/v1/public/oidc/callback` (also shown on the Identity page as **Redirect URI**)
    * Scopes: `openid`, `email`, `profile`
    * The ID token must include the user's `email`.
  </Tab>

  <Tab title="SAML">
    * ACS URL (Reply URL): shown on the Identity page, ending in `/auth/v1/sso/saml/acs`
    * Entity ID / metadata URL: shown on the Identity page, ending in `/auth/v1/sso/saml/metadata`
    * Name ID format: `EmailAddress`
    * Attributes: `email`, plus `firstName` and `lastName` if you want names filled in
  </Tab>
</Tabs>

### What Vibely checks on every sign-in

For OIDC, Vibely reads your IdP's discovery document, requires its `issuer` to match the URL you entered exactly, and validates the ID token's signature, issuer, audience, expiry, and nonce before signing anyone in.

For both protocols, the email your IdP sends must be on your workspace's **verified domain**. A sign-in for `someone@other.com` is rejected even if your IdP vouches for it.

### Require SSO

Once SSO works, you can turn on **Require SSO** to make your IdP the only way to join the workspace and to use Vibely as a member. It turns off invitations and external collaborators, and signs out any member (except the workspace owner) whose session didn't come through your IdP, such as a password or Google sign-in. You can also set a **Session duration** of 24 hours, 48 hours, or 7 days, after which members sign in through your IdP again. See [Require SSO and session duration](/features/workspace/identity#require-sso-and-session-duration).

<Tip>
  Test a sign-in with a colleague's account before requiring SSO.
</Tip>

## Provider-specific setup guides

Complete [Start SSO setup in Vibely](#start-sso-setup-in-vibely) first so you have the values to copy.

### Okta

<Tabs>
  <Tab title="OIDC">
    1. **Applications → Create App Integration → OIDC - OpenID Connect → Web Application**.
    2. Grant type: **Authorization Code**.
    3. Sign-in redirect URI: the Vibely redirect URI.
    4. Assign the people or groups who should get in.
    5. Copy the **Client ID** and **Client secret** into Vibely. The issuer is `https://<your-org>.okta.com`, or your custom authorization server's issuer if you use one. Use exactly the `issuer` value from the IdP's discovery document.
  </Tab>

  <Tab title="SAML">
    1. **Applications → Create App Integration → SAML 2.0**.
    2. **Single sign-on URL**: the ACS URL. **Audience URI**: the entity ID.
    3. **Name ID format**: `EmailAddress`. Map `email`, `firstName`, and `lastName`.
    4. Send the app's metadata URL to Vibely support. Paste the **Provider ID** you get back into Vibely.
  </Tab>
</Tabs>

### Microsoft Entra ID

<Tabs>
  <Tab title="OIDC">
    1. **App registrations → New registration**.
    2. Redirect URI: platform **Web**, the Vibely redirect URI.
    3. **Certificates & secrets → New client secret**. Copy the secret's **Value**, not its ID.
    4. The issuer is `https://login.microsoftonline.com/<tenant-id>/v2.0`. Use the v2.0 endpoint: v1.0 reports a different `issuer` and is rejected.
  </Tab>

  <Tab title="SAML">
    1. **Enterprise applications → New application → Create your own application** (non-gallery).
    2. **Single sign-on → SAML**. **Identifier** = entity ID, **Reply URL** = ACS URL.
    3. Claims: use `emailaddress` as the unique user identifier.
    4. Send the **App Federation Metadata URL** to Vibely support. Paste the **Provider ID** you get back into Vibely.
  </Tab>
</Tabs>

### Auth0

<Tabs>
  <Tab title="OIDC">
    1. **Applications → Create Application → Regular Web Application**.
    2. **Allowed Callback URLs**: the Vibely redirect URI.
    3. Copy the **Domain**, **Client ID**, and **Client Secret**.
    4. The issuer is `https://<your-tenant>.auth0.com/`. Vibely handles the trailing slash either way.
  </Tab>

  <Tab title="SAML">
    1. Create an application and turn on the **SAML2 Web App** add-on.
    2. **Application Callback URL**: the ACS URL.
    3. Send Auth0's metadata URL to Vibely support. Paste the **Provider ID** you get back into Vibely.
  </Tab>
</Tabs>

## Configure other providers

Any provider works if it supports one of the protocols:

* **OIDC**: the provider must publish `/.well-known/openid-configuration` at its issuer, support the authorization-code grant with PKCE, and put an `email` claim in the ID token. Register a confidential web client with the Vibely redirect URI and the `openid email profile` scopes.
* **SAML 2.0**: configure the ACS URL and entity ID, send `EmailAddress` as the Name ID, and send the metadata URL to Vibely support.

## Manage an existing SSO setup

* **Rotate the OIDC client secret**: paste the new secret and save. Leaving the field blank keeps the stored secret, so you can change other fields without re-entering it. The secret is stored encrypted and never shown again.
* **Change the domain**: changing the email domain clears verification. Verify again before sign-ins resume.
* **Turn SSO off**: turn off **Enable SSO** and save. Sign-in goes back to Google and email.

## Signing in

Your team goes to the normal Vibely sign-in page and enters their work email. If the domain is set up for SSO, they're sent to your IdP. A domain routes to SSO only when **all** of these are true:

* **Enable SSO** is on
* the domain is verified
* the workspace is on Business
* every field the protocol needs is filled in

## Troubleshooting

Errors come back to the sign-in page as `/login?error=<code>`.

| Code | What it means |
| - | - |
| `sso_domain_required` | No domain was submitted on the sign-in form. |
| `sso_unavailable` | The domain isn't set up for SSO, or the SAML handoff was refused. Check it's enabled, verified, on Business, and has a provider ID. |
| `sso_redirect_not_allowed` | A redirect pointed away from Vibely. |
| `oidc_domain_required` | The OIDC sign-in started without a domain. |
| `oidc_unavailable` | The same eligibility check as above, for OIDC. |
| `oidc_discovery_failed` | Vibely couldn't use your IdP's discovery document. Usually the document's `issuer` doesn't match the URL you entered, or it's missing an endpoint or its keys URL. |
| `oidc_state_invalid` | The sign-in took too long, the browser dropped part of it, or the link was reused. Start again. |
| `oidc_email_domain_mismatch` | The email in the ID token isn't on your verified domain. |
| `oidc_validation_failed` | The token's signature, audience, expiry, or nonce didn't check out. |
| `oidc_session_failed` | The token was valid but the session couldn't be created. Try again. |
| `rate_limited` | More than 20 sign-in attempts from one address in a minute. Wait and retry. |
| `sso_required` | Your workspace requires SSO and you signed in another way, such as a password or Google. Enter your work email and continue with SSO. |
| `sso_session_expired` | Your SSO session is older than the workspace's **Session duration**. Sign in again. |

<Note>
  An issuer mismatch is almost always a trailing slash or a version difference: Entra v1.0 instead of v2.0, or an Okta custom authorization server whose issuer is `/oauth2/<id>` rather than your org URL. Open `<issuer>/.well-known/openid-configuration` in a browser and copy its `issuer` field exactly.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Which plans include SSO?">
    The Business plan.
  </Accordion>

  <Accordion title="Can I start sign-in from my IdP's app dashboard?">
    No. Sign-in starts from the Vibely sign-in page.
  </Accordion>

  <Accordion title="Can I connect more than one identity provider?">
    No. A workspace has one SSO configuration for its one verified domain.
  </Accordion>

  <Accordion title="Do existing members need to do anything?">
    No. Next time they sign in with their work email, Vibely sends them to your IdP. Their account, projects, and role stay the same.
  </Accordion>

  <Accordion title="Can my IdP groups set workspace roles?">
    Through SCIM, yes. Vibely exposes three role groups (Admins, Editors, Viewers) that you map your IdP groups onto. See [SCIM](/features/workspace/scim#groups).
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Identity" icon="fingerprint" href="/features/workspace/identity">
    Verify your domain and choose how people join.
  </Card>

  <Card title="SCIM" icon="arrows-rotate" href="/features/workspace/scim">
    Provision and deprovision members from your IdP.
  </Card>
</CardGroup>


## Related topics

- [Vibely workspace](/features/workspace/overview.md)
- [Workspace admin settings](/features/workspace/admin-settings.md)
- [Manage workspace identity and user provisioning](/features/workspace/identity.md)
- [Vibely for Enterprise](/introduction/enterprise.md)
- [Workspace security center](/features/workspace/security-center.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.