Skip to content
Guides
Build guide

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.

Dharmendra Jagodana9 min read

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 says so plainly. If you would rather not hold a WorkOS account at all, Frontegg 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.

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 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 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:

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:

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:

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:

reasonWhat happenedWhat to do
sso_not_availableNo active enterprise has a verified domain for itGet the domain verified, or check they typed their work email
sso_email_mismatchThe identity provider sent an email off the domainsVerify that domain too, or fix the email at the IdP
sso_requiredThey used another way in and their company forbids itNothing, unless requiring SSO was a mistake
signup_disabledFirst-sign-in accounts are off and nobody invited themTurn 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. The short setup checklist is Set up Enterprise SSO.

npm i @buildbase/sdk
auth
enterprise-sso
workos
scim

Frequently Asked Questions

Who pays WorkOS when BuildBase runs enterprise SSO?

You do, directly. Single sign-on runs through your own WorkOS account, so WorkOS bills each enterprise connection to that account, and bills Directory Sync separately. BuildBase stores your client ID and an encrypted API key. Check WorkOS's own pricing page for the current rates.

Does the customer's IT admin need a BuildBase account?

No. They get a setup link, by email from WorkOS or opened with you on a call, and connect their identity provider in the WorkOS setup portal. The same link can walk them through verifying the company domain and connecting their directory.

What happens to people who used a password before single sign-on was required?

Once a company requires single sign-on, its people are refused at every other way in with a sentence telling them to use Continue with SSO. Sessions already open stay open. Turning the enterprise off, or enterprise sign-in off, lets everyone back in, which is the break-glass if the connection breaks.

What if my BuildBase plan stops including enterprise SSO?

Nothing that already works stops. People keep signing in through their company, directories keep syncing, and every screen still reads. New setup, such as another enterprise or domain, is locked and the API answers 402 with FEATURE_NOT_IN_PLAN.

Ship it

Create a project and run this guide against your own workspace.

Free plan7-day free trial on paid plansNo credit card required