Skip to content
BuildBase

Set up Enterprise SSO through your WorkOS account

Let a company you sell to sign its people in with its own identity provider, SAML or OIDC, through your own WorkOS account, step by step.

Enterprise single sign-on lets the people of a company you sell to sign in to your app with their company account: Okta, Microsoft Entra ID, Google Workspace, or any SAML or OIDC identity provider. Your login page shows Continue with SSO, they type their work email, and their company's identity provider does the rest. It runs through your own WorkOS account: BuildBase keeps your WorkOS client ID and an encrypted API key, makes one WorkOS organization per company, and runs the sign-in itself. WorkOS bills your account for each connection; see WorkOS pricing for its current rates. This guide is the setup in order; Enterprise SSO is the full reference.

Before you start

  • A WorkOS account, with its staging environment for testing and production for real companies.
  • An auth client with a login page, and an owner or admin role in the BuildBase console.
  • A plan that includes Enterprise SSO.

What goes where

Copy thisFromPaste it into
Client IDWorkOS, the environment's API Keys pageBuildBase, Authentication, Enterprise
API keyWorkOS, the same page (create one)BuildBase, the same tab
Redirect URIBuildBase, the Enterprise tab once the key is savedWorkOS, the application's Redirects, as the default
The company's domainThe companyBuildBase, the enterprise's Email domains; WorkOS verifies it

1. Connect your WorkOS account

  1. In WorkOS, on the environment's API Keys page, copy the client ID (client_...) and create an API key (sk_...), both from the same environment.
  2. In the console, open Authentication, then Enterprise, paste both, and choose Save and validate. BuildBase checks the key with WorkOS before it stores anything.
  3. Copy the redirect URI the tab now shows into WorkOS, under the application's Redirects, and make it the default.
  4. Leave AuthKit off in that environment: BuildBase uses WorkOS for single sign-on only.

2. Add the company

  1. On the same tab, Add enterprise with the company's name. It makes the company's WorkOS organization in your account.
  2. Decide Create accounts on first sign-in (on by default) and the Role for new accounts.
  3. In its Email domains, Add domain with the company's domain, such as acme.com. The company's IT admin verifies it in WorkOS; only a domain WorkOS verified sends anyone to the company's sign-in.

3. Hand the connection to the company's IT admin

From the enterprise, Invite the IT admin by email (tick Domain verification so the same email covers the domain), or Open the setup portal now on a call together. They connect their identity provider in WorkOS's setup portal and never need a BuildBase account. Send them the page for IT admins. The enterprise's Connection section shows when it is active.

4. Turn it on

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

The login page shows Continue with SSO. To have the company's people land in their workspaces, bind them in the enterprise's Workspaces section (step 6 of the reference).

Things to watch out for

  • Keep the client ID and the key from one environment. A staging key with a production client ID passes every check until the first sign-in, which then fails.
  • Require single sign-on only once the connection is active. With it on, the company's people are refused at every other way in (a password, a code, a passkey, a wallet, a social button, the second step of two-step), and until the connection works they cannot sign in at all. Its access policy can instead narrow the other ways, down to passkeys only.
  • A domain counts only while WorkOS verifies it. A pending domain routes nobody, and a subdomain is its own entry: the email the identity provider sends must be on a verified domain of that company, exactly.
  • Attach the method to every client the company's people use. A login page without Continue with SSO leaves them a sentence that points at a button the page does not have.
  • A sign-in screen of your own sends a PKCE challenge. PKCE is a check that the sign-in finishes in the same browser that started it, and the hosted page does it for you. Continue with SSO sends an S256 challenge, and the start refuses a request without one. So the code the identity provider sends back works only in the browser that pressed the button. If you build your own screen against the start, it must make a verifier, send its challenge and redeem the code with it (how).

Next steps