# How to add enterprise SSO to your SaaS through your own WorkOS account

> Enterprise SSO and SCIM for a B2B SaaS, in order: your WorkOS keys, the IT admin setup link, verified domains, required SSO, workspace bindings and the in-app screen.

- Source: https://www.buildbase.app/guides/add-enterprise-sso-saas-workos
- Section: Guides
- Author: Dharmendra Jagodana
- Published: 2026-11-03

## In short

Enterprise SSO in BuildBase runs through your own WorkOS account: paste its keys once, add each customer company and send its IT admin a setup link. Verified domains route people to their company sign-in, a first sign-in lands them in the workspaces you chose, and Directory Sync blocks leavers. Enterprise plan only.

The SAML handshake is the easy part of enterprise SSO. WorkOS does it, and does
it well. What eats the week is everything around the handshake: which company a
person belongs to, which workspace a new hire lands in, who on the customer's
side owns the connection, and what happens on the day their IT team removes
someone.

That is the part this guide is about. BuildBase does not put its own identity
layer in front of WorkOS. It runs on **your own WorkOS account**: you hold the
keys, WorkOS bills the connections to you, and BuildBase runs the sign-in, the
company records, the workspaces and the screens around it. If all you need is
the handshake, WorkOS on its own covers it, and our [WorkOS
comparison](/compare/workos-vs-buildbase) says so plainly. If you would rather
not hold a WorkOS account at all,
[Frontegg](/compare/frontegg-vs-buildbase) includes SSO connections on its free
plan and carries the vendor relationship for you.

When it works, a customer's employee opens your login page, presses **Continue
with SSO**, types their work email and signs in at Okta, Microsoft Entra, Google
Workspace or any SAML or OIDC identity provider. They come back signed in, inside
the workspaces you chose for their company, with the role you set.

> **Before you start:** A WorkOS account (its staging environment to test, production to go live), a
> BuildBase organization on the Enterprise plan, an auth client with a login
> page, and an owner or admin role in the BuildBase console. Enterprise SSO and
> Directory Sync are not on Launch, Grow or Scale. The in-app screen in step 9
> arrives in the next `@buildbase/sdk` release; 0.0.90 does not have it.

## 1. Connect your WorkOS account

In WorkOS, open the environment's **API Keys** page, copy the client ID
(`client_...`) and create an API key (`sk_...`). In the BuildBase console, open
**Authentication**, then **Enterprise**, paste both and choose **Save and
validate**. BuildBase asks WorkOS whether the key works before it stores
anything.

The tab then shows your **redirect URI**. Add it to the WorkOS application's
**Redirects** and make it the default. Leave AuthKit off in that environment:
BuildBase uses WorkOS for single sign-on only and runs the sign-in itself.

**What you should see:** the key shown only by its first and last characters,
and **Check the key** answering that it works.

One trap costs people an afternoon here. The client ID and the key must come
from the same WorkOS environment. A staging key with a production client ID
passes every check until the first real sign-in, which then fails, because
saving the key checks the key alone.

## 2. Add the customer company

Each company you sell to is an **enterprise**. **Add enterprise** creates a
WorkOS organization for it in your WorkOS account. Two settings come with it:

- **Create accounts on first sign-in**, on by default. An employee signing in
  through their company for the first time gets an account even when your public
  sign-up is closed, because their identity provider vouched for them.
- **Role for new accounts**, any of your user roles except owner.

**What you should see:** the enterprise, not yet connected.

## 3. Add the company's email domain

In the enterprise's **Email domains**, add the company's domain, say
`example.com`. It shows as **Pending** until the company's IT admin publishes
the DNS record WorkOS asks for, in WorkOS's Admin Portal. WorkOS decides; BuildBase
reads nobody's DNS.

The domain is more than routing. It is the check on every sign-in: the email the
identity provider asserts must be on one of the enterprise's verified domains,
or the sign-in is refused. Consumer domains such as `gmail.com` are refused
outright, and a domain one of your enterprises already holds is never handed to
another.

**What you should see:** the domain move to **Verified**. With your WorkOS
webhook registered from the console that takes seconds. Without it, up to 6
hours: the next time your server reads WorkOS's events. **Refresh from WorkOS**
asks now.

## 4. Send the IT admin their setup link

The customer's IT admin connects their identity provider in the WorkOS setup
portal. They never need a BuildBase account. From the enterprise, either:

- **Invite the IT admin by email.** WorkOS emails them the link. Tick **Domain
  verification** and the same email covers step 3 as well.
- **Open the setup portal now**, for when you do it together on a call. The link
  lasts 5 minutes. Anyone holding it can change the connection, so never forward
  it to the customer by chat or email.

Send them the [page for IT admins](https://docs.buildbase.app/authentication/enterprise-sso-it-admin)
with the invitation.

**What you should see:** the enterprise's **Connection** section turn active.

## 5. Turn it on

Under **Authentication**, **Methods**, add an **Enterprise SSO** method and
attach it to the auth client whose login page should offer it. Then turn
**Sign-in** on in the **Enterprise** tab.

**What you should see:** **Continue with SSO** under the client's other methods.
Pressed, it asks for a work email. It never says up front whether a domain has
SSO: someone whose company is not set up is told so after they continue, so the
button cannot be used to list your customers.

## 6. Choose where their people land

In the enterprise's **Workspaces** section, pick the workspaces its people join,
the role each one joins with, and **Save workspaces**.

Someone joins on their first sign-in through the company, whether the account is
new or an existing one linking up for the first time. After that it is a normal
membership with a memory: a person a workspace admin removes is not put back on
their next sign-in. A workspace belongs to one enterprise, and your plan's member
ceiling and the workspace's seats still apply. A join one of them refuses is
skipped, the person still signs in, and the enterprise shows **Needs a look**
with the reason.

**What you should see:** a test employee signing in and landing in the bound
workspace with the role you set, not on an empty "no workspaces" screen.

## 7. Require single sign-on, if the company wants it

Once the connection is active, the enterprise offers **Require single sign-on**.
With it on, the company's people are refused at every other way in (password,
magic link, email code, passkey, social sign-in and the rest) with a sentence
pointing them at **Continue with SSO**. An app with its own password form gets
`reason: "sso_required"` back from the sign-in call.

Two details we cared about. A wrong password still answers "Invalid email or
password", so the rule is never revealed to someone who does not hold the
credential. And it only holds while single sign-on can work: turning the
enterprise off, or enterprise sign-in off, lets everyone back in at once. That is
your break-glass. Sessions already open are left alone either way.

Order matters here. Turned on before the connection from step 4 is active, it
locks the company's people out completely.

## 8. Let the directory manage people (Directory Sync)

Single sign-on makes an account on first sign-in. It does nothing when someone
leaves. For that, turn on **Provision people from the directory** on the
enterprise and hand the directory step to the IT admin with **Set up
provisioning**. The portal gives them a SCIM endpoint and a bearer token to paste
into Okta, Microsoft Entra, Google Workspace or an HR system.

**What you should see:** the directory shown as **Linked**, with its last sync.

From then on, a person the directory adds gets an account and joins the bound
workspaces. A person it removes is **blocked, not deleted**: signed out
everywhere and taken out of the workspaces the enterprise put them in, with their
history kept. Directory groups can map to roles in the app or in a workspace,
and the highest role any group gives wins. Nobody gets an email about any of it,
because a company provisioning a thousand people would otherwise send a thousand
"you were added" emails.

WorkOS bills Directory Sync to your WorkOS account separately from single
sign-on. The [provisioning docs](https://docs.buildbase.app/authentication/enterprise-provisioning)
cover the group mappings in full.

## 9. Put the Single sign-on screen in your app

Your customer's workspace admins should not have to email you to find out whether
their connection works. From the next `@buildbase/sdk` release, the workspace
settings dialog grows a **Single sign-on** screen while enterprise sign-in is on:
the company's name, the connection's state and when it was checked, a Directory
sync card, a warning before a SAML certificate expires, and **Set up SSO**, which
opens the IT admin's setup for members who can edit the workspace's settings.

It shows on its own inside the settings dialog. To put it on a page of your own:

```tsx
import { EnterpriseAccess } from '@buildbase/sdk/react';

export function SsoPage() {
  // The current workspace; pass workspaceId="..." for another one.
  return <EnterpriseAccess />;
}
```

Or build your own around the headless hook:

```tsx
import { useEnterprise } from '@buildbase/sdk/react';

export function SsoStatus({ workspaceId }: { workspaceId: string }) {
  const { status, loading, opening, openSetup } = useEnterprise(workspaceId);

  if (loading || !status) return null;
  if (!status.available) return <p>This workspace has no company sign-in.</p>;

  return (
    <div>
      <p>
        {status.enterprise.name}: {status.sso.connectionState}
      </p>
      <button type="button" disabled={opening} onClick={() => openSetup()}>
        Set up SSO
      </button>
    </div>
  );
}
```

`openSetup()` has to run from a click. The server may first ask the admin to
confirm it is them, so the link is fetched before any tab opens. From your
backend, the same two calls exist on the server client:

```ts
import BuildBase from '@buildbase/sdk';

const bb = BuildBase({ serverUrl, orgId, getSessionId });

const status = await bb.enterprise.status(workspaceId); // { available: false } or the company
const { url } = await bb.enterprise.createSetupLink(workspaceId);
// `url` is a credential: redirect the browser to it, never log or store it.
```

We have not run these three samples against a live tenant for this post; they
match the exports and the README of the SDK release they arrive in.

## What breaks, and how to tell

A refused sign-in sends the person back to your login page with a `reason`. The
ones you will meet first:

| `reason`             | What happened                                          | What to do                                                    |
| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
| `sso_not_available`  | No active enterprise has a verified domain for it      | Get the domain verified, or check they typed their work email |
| `sso_email_mismatch` | The identity provider sent an email off the domains    | Verify that domain too, or fix the email at the IdP           |
| `sso_required`       | They used another way in and their company forbids it  | Nothing, unless requiring SSO was a mistake                   |
| `signup_disabled`    | First-sign-in accounts are off and nobody invited them | Turn it on, or invite them                                    |

**"Use SSO" with no SSO button.** The auth client they signed in through has no
Enterprise SSO method attached. Attach it to every client the company's people
use.

**"The setup never came back."** Do not count on the WorkOS portal returning the
IT admin to your app. When we tested on WorkOS's staging environment on 14
October 2026, it stayed on "Connection activated" once the connection worked and
never followed the return URL. The SDK screen covers it by reading the status
again whenever the admin returns to the tab, for 30 minutes after opening the
setup.

**Everyone at one company locked out on the same day.** A SAML connection trusts
one signing certificate, and those expire. BuildBase reads WorkOS's expiry
warnings, badges the enterprise in your console, and shows the company's admins
**Renew the certificate** in your app, so their IT admin can fix it before the
date rather than after.

**Your plan changes.** If your BuildBase plan stops including enterprise SSO,
nothing that works stops: people keep signing in and directories keep syncing.
New setup is locked, and the API answers `402` with `FEATURE_NOT_IN_PLAN`.

The full reference, including several identity providers per company, the access
policy and the company's audit trail, is in the [enterprise SSO
docs](https://docs.buildbase.app/authentication/enterprise-sso). The short setup
checklist is [Set up Enterprise SSO](https://docs.buildbase.app/sign-in-setup/enterprise-sso).

```bash
npm i @buildbase/sdk
```
