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.
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.
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 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:
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. The short setup checklist is Set up Enterprise SSO.
npm i @buildbase/sdk