Enterprise SSO (SAML & OIDC / OAuth)

The public landing page and Documentation hub summarize this capability for buyers; this guide is the operator setup reference.

The app supports procurement-friendly sign-in alongside email and password:

SAML 2.0 enterprise SSO — Supabase Auth signInWithSSO (SP-initiated). Typical IdPs: Okta, Microsoft Entra ID (Azure AD), Google Workspace, Ping, OneLogin, etc.
OIDC / OAuth providers — Optional buttons for providers you enable in Supabase (e.g. Microsoft azure, Google google) via signInWithOAuth, using the same /auth/callback route as SAML.

SAML is configured in Supabase and your IdP, not only in this repo. This document ties product behavior to dashboard steps.

Prerequisites (SAML)

Supabase plan: SAML SSO is available on Pro and above (see Supabase pricing).
CLI: Supabase CLI v1.46.4+ for supabase sso commands.
Enable SAML on the project: Dashboard → Authentication → Providers → enable SAML 2.0.

Official reference: Single Sign-On with SAML 2.0.

Redirect URL (required)

Add your app callback to Redirect URLs (Dashboard → Authentication → URL configuration):

URL	Purpose
`https://<your-app-host>/auth/callback`	Exchange authorization code for session (SAML + OAuth)

Set NEXT_PUBLIC_APP_URL to the same canonical origin (e.g. https://app.example.com) in every environment so the client builds the correct redirectTo for signInWithSSO / signInWithOAuth.

Site URL in Supabase should match your primary app origin.

Register an IdP (SAML)

Use metadata from your customer’s IdP:

supabase sso add --type saml --project-ref <YOUR_PROJECT_REF> \
  --metadata-url 'https://idp.example.com/metadata' \
  --domains example.com

Or --metadata-file /path/to/metadata.xml. Associate email domains with the connection so users can enter user@example.com on the login screen.

Share Supabase’s ACS URL and Entity ID from the docs or:

supabase sso info --project-ref <YOUR_PROJECT_REF>

Important: SSO users do not automatically merge with existing email/password accounts that share the same email. Prefer one auth method per user or plan an account-linking strategy (Supabase docs — user accounts and identities).

Enable the login UI (this app)

Copy from .env.example:

Variable	Purpose
`NEXT_PUBLIC_AUTH_ENTERPRISE_SSO`	Set to `true` to show the SAML SSO panel (work email / domain, or fixed provider below).
`NEXT_PUBLIC_SSO_PROVIDER_ID`	Optional. UUID of a single registered IdP from `supabase sso show` — skips domain entry (single-tenant or intranet bookmark flows).
`NEXT_PUBLIC_AUTH_OIDC_PROVIDERS`	Optional. Comma-separated Supabase provider keys for OAuth buttons, e.g. `azure,google`. Each must be enabled in Dashboard → Authentication → Providers.

After deploy, verify Redirect URLs and NEXT_PUBLIC_APP_URL match the URL users see in the browser.

IdP-initiated SAML vs PKCE

Traditional IdP-initiated SAML flows conflict with PKCE (no prior code_verifier). Supabase recommends an SP-initiated bookmark: host a URL that calls signInWithSSO and point the IdP “app tile” at that URL. See Why doesn't IdP-initiated SAML flow work with PKCE?.

Multi-tenant SaaS

You can register multiple SAML connections (one per customer) with supabase sso add. The login form uses email domain to pick the IdP. For RLS / tenancy, you can use JWT claims such as auth.jwt()#>>'{amr,0,provider}' (SSO provider UUID) — see the same Supabase SAML guide.

Operations checklist

SAML enabled on Supabase project (Pro+).
IdP metadata + domains registered (supabase sso add).
/auth/callback on allowlist; NEXT_PUBLIC_APP_URL set.
NEXT_PUBLIC_AUTH_ENTERPRISE_SSO=true (and optional NEXT_PUBLIC_SSO_PROVIDER_ID / NEXT_PUBLIC_AUTH_OIDC_PROVIDERS).
OAuth providers enabled in Dashboard if using OIDC buttons.
Sales/support runbook: duplicate email accounts if users mix password + SSO.

Code map

Login UI: app/login/page.tsx, components/auth/EnterpriseAuthPanels.tsx
Callback: app/auth/callback/route.ts (exchangeCodeForSession)
Env parsing: lib/auth/enterpriseAuthConfig.ts
Domain normalization: lib/auth/workDomain.ts