How to add enterprise SSO and SCIM to a Better Auth app

Adding enterprise SSO to a Better Auth app means letting a customer's employees sign in through their own identity provider (Okta, Microsoft Entra ID, Google Workspace and others) while your app keeps issuing its normal Better Auth session. SCIM, usually called directory sync, adds the other half: the customer's IT team creates and removes users in their directory, and your app follows along automatically.

What you'll build

A small Better Auth plugin that sends enterprise users to WorkOS SSO and turns the returned profile into a Better Auth session, a "Connect SSO" button for users who already have an account, a webhook route that signs users out when IT deactivates them, and a settings page link that lets each customer's IT admin configure everything themselves.

Here's the path you'll follow:

1. Create a WorkOS organization for each enterprise customer and keep a table of their verified domains.
2. Send users with an enterprise email to SSO from your sign-in page, including users who start from their IdP's app launcher.
3. Turn the SSO profile into a Better Auth session, keyed on the organization and IdP user ID.
4. Let existing users connect SSO to their account, then require SSO per customer.
5. Revoke sessions when the customer's IT team deactivates someone, using Directory Sync.
6. Give each customer's IT admin a self-serve setup link with the Admin Portal.
7. Test every path with the Test Identity Provider before a customer does.

Why add a provider instead of building SAML into your app?

Better Auth gives you email and password, social login, sessions and organizations in your own codebase, and that is often exactly right for self-serve users. The pressure changes with the first enterprise deal. The customer's security questionnaire asks for SAML SSO, their IT team asks for SCIM provisioning, and every new customer brings a different identity provider with its own metadata, certificates and attribute names.

You can build that inside your app, but then SAML response validation, certificate rotation, and each IdP's SCIM dialect become code you own and patch. The setup work also lands on your team: someone has to collect metadata URLs and certificates from each customer's IT admin and keep them current.

The approach in this guide splits the work:

• Better Auth stays in charge of users, sessions and every non-enterprise sign-in method. Nothing about your existing login changes.
• WorkOS handles the enterprise parts: the SAML or OIDC exchange with each customer's IdP (SSO), user lifecycle events from their directory (Directory Sync), and a hosted setup flow for their IT admin (Admin Portal).

If you built your own auth rather than using a library, the same pattern is covered in How to add SSO to your homegrown auth. This guide goes further: it shows how to create a real Better Auth session from the SSO profile, how to connect existing accounts safely, and how to handle deprovisioning.

How do Better Auth and WorkOS fit together?

Each enterprise customer becomes a WorkOS organization. The organization holds the customer's SSO connection, their directory, and the email domains they've verified. Your app only needs to remember one thing: which WorkOS account, identified by the organization and the user's IdP ID, belongs to which Better Auth user.

What do you need before you start?

The code in this tutorial assumes this stack. Other frameworks work the same way, since the plugin runs inside Better Auth and the webhook is a plain request handler.

• Node.js 20 or later, with TypeScript.
• Better Auth 1.7.x with a database adapter, mounted at /api/auth. The plugin uses Better Auth's plugin API and internal adapter, so pin your version and check the release notes when you upgrade.
• Next.js with the App Router for the webhook route. Any framework that gives you the raw request works.
• Packages: npm install @workos-inc/node zod.
• A WorkOS account. From the dashboard you need your API key (WORKOS_API_KEY), your client ID (WORKOS_CLIENT_ID), and a redirect URI pointing at the callback you'll build: https://your-app.com/api/auth/workos/callback.
• A webhook endpoint registered in the WorkOS dashboard at https://your-app.com/api/webhooks/workos, and its signing secret (WORKOS_WEBHOOK_SECRET).
• A database table for enterprise domains. The examples use a generic db client, so swap in your ORM.

  
// lib/workos.ts
import { WorkOS } from '@workos-inc/node';

export const workos = new WorkOS(process.env.WORKOS_API_KEY);
export const WORKOS_CLIENT_ID = process.env.WORKOS_CLIENT_ID!;
  

How do you model each enterprise customer?

Create one WorkOS organization per enterprise customer, and store its ID next to the customer record you already have (or on your Better Auth organization, if you use that plugin).

  
const org = await workos.organizations.createOrganization({
  name: 'Acme Corp',
  externalId: acmeCustomerId, // your own ID for this customer
});
// Save org.id on your customer record.
  

Then have the customer's IT admin verify their email domains through the Admin Portal (covered further down). Keep a small table in your own database that maps each verified domain to its organization, plus a per-customer flag for whether SSO is required:

  
// Your schema, in whatever ORM you use
type EnterpriseDomain = {
  domain: string;               // 'acme.com', lowercase, unique
  workosOrganizationId: string; // 'org_01H...'
  ssoRequired: boolean;         // turn on once the customer's users have moved to SSO
};

// lib/enterprise-domains.ts
export async function getEnterpriseDomain(email: string) {
  const domain = email.split('@')[1]?.toLowerCase();
  if (!domain) return null;
  return db.enterpriseDomain.findUnique({ where: { domain } });
}
  

You fill this table from WorkOS events: add a row on organization_domain.verified and remove it on organization_domain.deleted (the webhook route later in this guide handles both). A local table keeps the sign-in page fast, because it doesn't need an API call for every email someone types.

How do you send enterprise users to SSO at sign-in?

Ask for the email first. If its domain is in your enterprise domain table, start SSO for that organization. Otherwise, show your normal Better Auth form. This pattern is often called home realm discovery.

Everything lives in one Better Auth plugin, so the endpoints are mounted under your existing auth route (for example /api/auth/workos/start) and get Better Auth's request context, cookies and secret.

  
// lib/workos-sso-plugin.ts
import type { BetterAuthPlugin } from 'better-auth';
import { createAuthEndpoint, APIError } from 'better-auth/api';
import { z } from 'zod';
import { workos, WORKOS_CLIENT_ID } from './workos';
import { getEnterpriseDomain } from './enterprise-domains';

const STATE_COOKIE = 'workos_sso_state';

type SsoState = {
  state: string;
  organizationId?: string; // set when we know which org to expect
  connectionId?: string;   // set for IdP-initiated sign-in
  linkUserId?: string;     // set when a signed-in user is connecting SSO
};

// Shared by every endpoint that starts SSO.
async function startSso(ctx: any, expected: Omit<SsoState, 'state'>, loginHint?: string) {
  const state = crypto.randomUUID();
  await ctx.setSignedCookie(
    STATE_COOKIE,
    JSON.stringify({ state, ...expected }),
    ctx.context.secret,
    { httpOnly: true, secure: true, sameSite: 'lax', path: '/', maxAge: 600 },
  );

  return workos.sso.getAuthorizationUrl({
    ...(expected.connectionId
      ? { connection: expected.connectionId }
      : { organization: expected.organizationId! }),
    clientId: WORKOS_CLIENT_ID,
    redirectUri: `${ctx.context.baseURL}/workos/callback`,
    state,
    loginHint,
  });
}

export const workosSso = () =>
  ({
    id: 'workos-sso',
    endpoints: {
      workosStart: createAuthEndpoint(
        '/workos/start',
        { method: 'POST', body: z.object({ email: z.string().email() }) },
        async (ctx) => {
          const entry = await getEnterpriseDomain(ctx.body.email);
          if (!entry) return ctx.json({ sso: false });

          const url = await startSso(
            ctx,
            { organizationId: entry.workosOrganizationId },
            ctx.body.email,
          );
          return ctx.json({ sso: true, url });
        },
      ),
      // workosIdpInitiated, workosLink and workosCallback are added below.
    },
  }) satisfies BetterAuthPlugin;
  

The state value is what ties the response back to this browser. Without it, an attacker could finish an SSO flow of their own and trick a victim's browser into landing on your callback, signing the victim into the attacker's account. The signed cookie also remembers which organization you expect, which the callback checks.

On the client, call the endpoint when the user submits their email, and either redirect to url or reveal the password field and social buttons:

  
const res = await fetch('/api/auth/workos/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email }),
});
const { sso, url } = await res.json();
if (sso) window.location.href = url;
else showPasswordStep();
  

What about users who start from their IdP's app launcher?

Many employees open apps from the Okta or Entra dashboard rather than your sign-in page. For these IdP-initiated sign-ins, WorkOS doesn't post an unsolicited assertion to your callback. It redirects the user to your sign-in endpoint with a connection_id query parameter, and your app starts a normal flow from there, as the IdP-initiated SSO guide describes. Set that endpoint in the WorkOS dashboard to https://your-app.com/api/auth/workos/idp-initiated.

  
workosIdpInitiated: createAuthEndpoint(
  '/workos/idp-initiated',
  { method: 'GET', query: z.object({ connection_id: z.string() }) },
  async (ctx) => {
    const url = await startSso(ctx, { connectionId: ctx.query.connection_id });
    throw ctx.redirect(url);
  },
),
  

Because the flow restarts in your app, it still gets a fresh state, and the callback checks that the profile came from the same connection.

How do you turn the SSO profile into a Better Auth session?

When the IdP is done, WorkOS redirects to your callback with a code and the state you sent. Before you trust anything in the profile, the callback checks three things:

1. The state matches the signed cookie, so the response belongs to a sign-in this browser started.
2. profile.organizationId is set and is the organization you expected (or the profile came from the connection you expected). The SSO guide is explicit that you should always validate the returned organization ID rather than rely on email domains.
3. The email's domain is one this organization has verified. If a customer needs guests from other domains to use SSO, handle that as an explicit allowlist per customer.

Then it decides which Better Auth user the sign-in belongs to. The key rule: identify SSO users by their organization and IdP user ID, never by email. The profile reference describes idp_id as the user ID assigned by the identity provider, and notes it can link the profile to Directory Sync records. Email addresses change and can be reused. The pair of organization ID and idp_id stays stable, and Directory Sync events carry the same two fields, which the deprovisioning step relies on.

  
// lib/workos-sso-plugin.ts (continued)
import { handleOAuthUserInfo } from 'better-auth/oauth2';
import { setSessionCookie } from 'better-auth/cookies';

const accountKey = (organizationId: string, idpId: string) =>
  `${organizationId}:${idpId}`;

// Inside endpoints:
workosCallback: createAuthEndpoint(
  '/workos/callback',
  { method: 'GET', query: z.object({ code: z.string(), state: z.string() }) },
  async (ctx) => {
    // 1. State
    const raw = await ctx.getSignedCookie(STATE_COOKIE, ctx.context.secret);
    ctx.setCookie(STATE_COOKIE, '', { path: '/', maxAge: 0 });
    const expected: SsoState | null = raw ? JSON.parse(raw) : null;
    if (!expected || expected.state !== ctx.query.state) {
      throw new APIError('BAD_REQUEST', { message: 'Invalid SSO state' });
    }

    const { profile } = await workos.sso.getProfileAndToken({
      code: ctx.query.code,
      clientId: WORKOS_CLIENT_ID,
    });

    // 2. Organization (or connection, for IdP-initiated sign-in)
    const orgId = profile.organizationId;
    if (
      !orgId ||
      (expected.organizationId && orgId !== expected.organizationId) ||
      (expected.connectionId && profile.connectionId !== expected.connectionId)
    ) {
      throw new APIError('UNAUTHORIZED', { message: 'Unexpected organization' });
    }

    // 3. Email domain verified by this organization
    const entry = await getEnterpriseDomain(profile.email);
    if (!entry || entry.workosOrganizationId !== orgId) {
      throw ctx.redirect('/sign-in?error=domain_not_allowed');
    }

    const key = accountKey(orgId, profile.idpId);

    // Connecting SSO to an account the user is already signed in to
    if (expected.linkUserId) {
      const owner = await ctx.context.internalAdapter.findAccountByKey({
        providerId: 'workos',
        accountId: key,
      });
      if (owner && owner.userId !== expected.linkUserId) {
        throw ctx.redirect('/settings/security?error=sso_already_linked');
      }
      if (!owner) {
        await ctx.context.internalAdapter.linkAccount({
          userId: expected.linkUserId,
          providerId: 'workos',
          accountId: key,
        });
      }
      throw ctx.redirect('/settings/security?sso=connected');
    }

    // Normal SSO sign-in
    const result = await handleOAuthUserInfo(ctx, {
      userInfo: {
        id: profile.id,
        email: profile.email.toLowerCase(),
        name:
          [profile.firstName, profile.lastName].filter(Boolean).join(' ') ||
          profile.email,
        image: null,
        // Don't let Better Auth link this login to an existing user by email.
        emailVerified: false,
      },
      account: { providerId: 'workos', accountId: key },
      isTrustedProvider: false,
      trustProviderByName: false,
    });

    if (result.error === 'account not linked') {
      // Someone already has this email. They connect SSO once, while signed in.
      throw ctx.redirect('/sign-in?error=connect_sso_from_settings');
    }
    if (result.error || !result.data) {
      throw ctx.redirect('/sign-in?error=sso_failed');
    }

    await setSessionCookie(ctx, {
      session: result.data.session,
      user: result.data.user,
    });
    throw ctx.redirect('/dashboard');
  },
),
  

handleOAuthUserInfo is the helper Better Auth's own social and SSO flows use. It looks up the linked account first, creates a new user when there's no match, and creates the session. Passing emailVerified: false and isTrustedProvider: false tells it never to attach this login to an existing user just because the email matches. Those cases go through the linking flow below instead.

Register the plugin like any other:

  
// lib/auth.ts
import { betterAuth } from 'better-auth';
import { workosSso } from './workos-sso-plugin';

export const auth = betterAuth({
  // ...your existing database, emailAndPassword and socialProviders config
  plugins: [workosSso()],
});
  

How do existing users connect their account to SSO?

When a customer turns on SSO, some of their employees already have accounts in your app with passwords or social login. Rather than matching them by email, let each of them connect SSO once, from a page where they're already signed in. That proves they own both the existing account and the SSO identity.

  
// Inside endpoints:
import { sessionMiddleware } from 'better-auth/api';

workosLink: createAuthEndpoint(
  '/workos/link',
  { method: 'POST', use: [sessionMiddleware] },
  async (ctx) => {
    const user = ctx.context.session.user;
    const entry = await getEnterpriseDomain(user.email);
    if (!entry) throw new APIError('BAD_REQUEST', { message: 'No SSO for this domain' });

    const url = await startSso(
      ctx,
      { organizationId: entry.workosOrganizationId, linkUserId: user.id },
      user.email,
    );
    return ctx.json({ url });
  },
),
  

Put a "Connect SSO" button on the account settings page that calls this endpoint and redirects to url. The callback's linking branch attaches the SSO identity to the signed-in user, and refuses if that identity already belongs to someone else.

Should enterprise users still be able to use a password?

Once a customer's users have connected SSO, their IT team will expect every sign-in to go through their IdP, so their policies (MFA, device checks, offboarding) apply. Sending users to SSO from the email step covers the normal path, but the password endpoint still accepts direct requests. When the customer is ready, set ssoRequired on their domains and add a before hook to the plugin:

  
// Add to the plugin object, next to endpoints:
import { createAuthMiddleware } from 'better-auth/api';

hooks: {
  before: [
    {
      matcher: (context) => context.path === '/sign-in/email',
      handler: createAuthMiddleware(async (ctx) => {
        const email = ctx.body?.email;
        const entry = email ? await getEnterpriseDomain(email) : null;
        if (entry?.ssoRequired) {
          throw new APIError('FORBIDDEN', {
            message: 'Your organization signs in with SSO.',
          });
        }
      }),
    },
  ],
},
  

Apply the same check to password reset, magic link and email OTP endpoints if you use them. Turning ssoRequired on per customer, rather than for every verified domain, gives existing users time to connect SSO first, and lets you keep a password-based break-glass admin if a customer asks for one.

How do you deprovision users with Directory Sync?

SSO stops a removed employee from signing in again. It doesn't end the session they already have. Directory Sync closes that gap: when the customer's IT team deactivates someone, WorkOS sends your app an event, and your app revokes their Better Auth sessions right away.

The Directory Sync events guide describes the cases you need to handle:

Handle both deactivation events. By default, WorkOS deletes directory users that move to the inactive state, so depending on your inactive user setting you may see the update, the delete, or both. A handler that treats either one as "revoke access" works with either setting.

Because the account key you stored at sign-in is the organization ID plus idp_id, and directory users carry both fields, the webhook finds the right Better Auth user without matching on email. The same route keeps your enterprise domain table up to date:

  
// app/api/webhooks/workos/route.ts (Next.js App Router)
import { workos } from '@/lib/workos';
import { auth } from '@/lib/auth';

export async function POST(req: Request) {
  const payload = await req.json();
  const sigHeader = req.headers.get('workos-signature') ?? '';

  let event;
  try {
    event = await workos.webhooks.constructEvent({
      payload,
      sigHeader,
      secret: process.env.WORKOS_WEBHOOK_SECRET!,
    });
  } catch {
    return new Response('Invalid signature', { status: 400 });
  }

  switch (event.event) {
    case 'organization_domain.verified':
      await db.enterpriseDomain.upsert({
        where: { domain: event.data.domain },
        create: {
          domain: event.data.domain,
          workosOrganizationId: event.data.organizationId,
          ssoRequired: false,
        },
        update: { workosOrganizationId: event.data.organizationId },
      });
      break;

    case 'organization_domain.deleted':
      await db.enterpriseDomain.deleteMany({ where: { domain: event.data.domain } });
      break;

    case 'dsync.user.updated':
    case 'dsync.user.deleted': {
      const deactivated =
        event.event === 'dsync.user.deleted' || event.data.state === 'inactive';
      if (!deactivated) break;

      const { internalAdapter } = await auth.$context;
      const account = await internalAdapter.findAccountByKey({
        providerId: 'workos',
        accountId: `${event.data.organizationId}:${event.data.idpId}`,
      });
      if (account) {
        await internalAdapter.deleteUserSessions(account.userId);
        await markUserInactive(account.userId); // your own app logic
      }
      break;
    }
  }

  return new Response('ok');
}
  

If you keep an inactive flag on the user, also check it in the SSO callback before creating a session, so a user who's still signed in at their IdP can't come straight back.

A few things make this production-ready:

• Respond fast and process in the background. The webhooks guide recommends returning 200 as quickly as possible and queuing the work.
• Make handlers idempotent. Events can arrive more than once or out of order. Record processed event IDs, and compare updated_at before overwriting data.
• Reconcile on a schedule. Run a periodic job that lists each directory's users through the API and revokes anyone who's no longer active, so a missed webhook doesn't leave someone with access.
• Read group memberships from the API. If you map directory groups to roles, fetch the user's groups with the List Directory Groups endpoint rather than relying on the user and group objects embedded in group membership events.
• Tell Okta customers to enable deactivation. In Okta, deactivations only reach your app if the customer has turned on deactivating users in the app's provisioning settings. Add that to your setup checklist for Okta customers.

Directory Sync also lets you create users before their first sign-in and map directory groups to roles. Both build on the same account key. The Directory Sync docs cover groups and role mapping.

How do customers' IT admins set this up?

This is the part that usually eats the most time when you build SSO yourself: emails back and forth for metadata URLs, certificates and attribute mappings. With the Admin Portal, you add a button to your customer's settings page, and their IT admin follows step-by-step instructions for their specific identity provider.

  
// Server action or route handler, called when the admin clicks "Configure SSO"
const { link } = await workos.adminPortal.generateLink({
  organization: customer.workosOrganizationId,
  intent: 'sso', // or 'dsync', 'domain_verification', 'certificate_renewal'
  returnUrl: 'https://your-app.com/settings/security',
});
// Redirect the admin to link right away.
  

Generate the link when the admin clicks, and redirect immediately. The portal link reference notes that links expire five minutes after they're issued, so don't email them or store them. Offer three buttons: verify domain (needed for routing and safe linking), configure SSO, and configure directory sync. Only show them to users who are admins of that customer in your app.

How do you test it before a customer does?

Every WorkOS staging environment includes a Test Identity Provider, so you can run the full flow without access to a real Okta or Entra tenant. Create a test organization, add a domain you control, and walk through:

• A new user signing in through SSO (just-in-time creation).
• An existing password user signing in through SSO for the first time (sent to connect SSO from settings), then connecting it while signed in.
• A profile whose email domain the organization hasn't verified (rejected).
• A callback with a missing or mismatched state (rejected).
• A password sign-in on a domain with ssoRequired on (blocked by the hook).
• A deactivation in the directory, followed by a request with the old session cookie (signed out).

The SSO testing guide walks through the Test Identity Provider setup.

What did you build?

Your app now supports enterprise SSO and directory sync without changing how anyone else signs in:

When should you move everything to WorkOS instead?

The hybrid setup is a good fit when most of your users are self-serve and a handful of customers need enterprise features. It gets heavier as enterprise becomes a bigger share of the business: you're running two systems for sign-in, organizations and roles, and keeping them in sync is your job.

If you find yourself rebuilding organization switching, role mapping or audit logs around this plugin, it may be time to move the whole user base to AuthKit, which includes sessions, organizations, roles, SSO and directory sync in one place. The Better Auth migration guide covers importing users, password hashes, organizations and memberships, and you can do it gradually from the setup in this post.

Add enterprise SSO without replacing your auth

WorkOS gives you SSO with every major identity provider, Directory Sync, and a self-serve Admin Portal for your customers' IT teams, through one API that works next to the auth you already have. Pricing is per connection, so you pay as enterprise customers arrive. Start with the SSO docs, or see the same pattern for homegrown auth.