Single sign-on

Better Auth's SSO plugin. Each organization registers its own identity provider (Okta, Microsoft Entra ID, Google Workspace, …), and its members sign in through it with their work email.

Turning it on

pnpm add @better-auth/sso

export default defineNuxtConfig({
  betterAuthUi: {
    organization: { enabled: true },
    sso: {
      enabled: true,
      // New providers work once a DNS record proves the organization owns their domains.
      domainVerification: true
    }
  }
})

export default defineServerAuth({
  trustedOrigins: ['https://your-org.okta.com', 'https://login.microsoftonline.com']
})

Signing in

The sign-in page gets a "Sign in with SSO" button. People type either:

• their work email: the provider is found by the email's domain;
• their organization's slug: the organization's provider is used.

They're sent to their identity provider, and come back signed in. New users land on the account page, and a provider that fails comes back with a message.

People who sign in through an organization's provider join that organization, with defaultRole or the role getRole gives them (see Who joins as what).

Setting up a provider

Each organization's page gets an SSO tab, for its owners and admins (Better Auth allows only those roles).

Adding one

Add provider asks for:

More settings has the rest: scopes, PKCE, token authentication, audience, NameID format, algorithms, signed assertions and requests, profile mapping, and your own provider fields.

What to give the identity provider

Each provider on the tab shows the addresses its identity provider needs, with copy buttons:

• OIDC: the redirect URI, https://your-site/api/auth/sso/callback/<provider id>.
• SAML: the ACS URL, https://your-site/api/auth/sso/saml2/sp/acs/<provider id>, and a link to the service provider metadata XML.

Verifying the domain

With domainVerification, a new provider can't sign anyone in until its domains are verified:

1. The tab shows a TXT record to add to each domain's DNS: its name, _better-auth-token-<provider id>.<domain>, and Show the value.
2. Add the record, and wait for DNS to update.
3. Press Verify domain.

Editing and deleting

Edit a provider from its card; fields left empty, like secrets and certificates, stay as they are. Deleting asks first: its members can't sign in through it any more.

Who joins as what

Members who sign in through their organization's provider join it with organizationProvisioning.defaultRole. To decide per person, from what the provider says about them, write getRole in a file and point serverOptions at it:

export default defineNuxtConfig({
  betterAuthUi: {
    sso: {
      enabled: true,
      organizationProvisioning: { defaultRole: 'member' },
      serverOptions: './server/auth/sso.ts'
    }
  }
})

export default {
  organizationProvisioning: {
    getRole: async ({ userInfo }) =>
      userInfo.attributes?.department === 'IT' ? 'admin' : 'member'
  }
}

The same file takes Better Auth's other function options: provisionUser, resolveUser, guardProviderMutation, resolvePrivateKey and defaultSSO.

In the admin

A Single sign-on page lists every provider: its protocol, domains and whether they're verified, its organization, and who added it. It never shows secrets. The configuration page shows whether SSO and domain verification are on.

Options