SAML 2.0 single sign-on

SAML 2.0 single sign-on lets people sign in to your app through their company's identity provider (IdP), such as Okta, Microsoft Entra ID, Google Workspace, OneLogin or JumpCloud. You add one SAML provider per customer organisation and link it to their email domains. Their users then sign in with their work account, and Supabase Auth creates or updates the user in your project.

SAML is switched on for every SupaHost project, on every plan. There's no extra charge per connection or per user.

How it works

1. Your app calls signInWithSSO with the user's email domain (or a provider ID).
2. Auth finds the matching SAML provider and returns a URL that sends the user to their IdP.
3. The user signs in at their IdP, which posts a signed SAML response back to your project.
4. Auth checks the response, creates or updates the user, and redirects to your app with a session, like any other sign-in.

In the SAML setup, your project is the service provider (SP), and your customer's IdP is the identity provider.

Step 1: give the IdP your project's SP details

In the dashboard, open your project's Auth tab and scroll to SAML 2.0 single sign-on. The card shows three values to send to your customer's IdP admin:

Most IdPs can import everything from the metadata URL. If theirs asks for values one at a time, use the entity ID and ACS URL. Have them send the user's email as the NameID (or as an email attribute).

These addresses always use your project's supahost.space host, even after you add a custom domain. That way the IdP setup keeps working if your domains change.

Step 2: add the provider in SupaHost

Your customer's IdP admin will give you a metadata URL or a metadata XML file. On the Auth tab, click Add SAML provider, then:

1. Choose Metadata URL and paste it, or choose Paste XML and paste the file's contents. A URL is better if the IdP rotates its certificates, because Auth re-reads it.
2. Under Email domains, list the domains whose users should use this provider, such as acme.com, acme.co.uk.
3. Optionally add an Attribute mapping (see below), then click Add provider.

The provider appears in the list with its ID. Only the instance owner can add, edit or remove providers. Team members can see them.

Step 3: sign users in from your app

Sign in by email domain:

const { data, error } = await supabase.auth.signInWithSSO({
  domain: 'acme.com',
  options: { redirectTo: 'https://app.example.com/auth/callback' },
})
if (data?.url) window.location.href = data.url

Or by provider ID, if a customer has several domains or you store the ID per organisation:

await supabase.auth.signInWithSSO({ providerId: '7f1c2a4e-…' })

The redirectTo URL must be allowed under Redirect URLs on the Auth tab, the same as for OAuth. On the server side, handle the callback the same way as other redirect sign-ins (see Server-side auth and SSR).

A common pattern is a single "Continue with SSO" field on your sign-in page: take the user's email, use the part after @ as the domain, and fall back to a password sign-in if signInWithSSO returns an error saying no provider matches.

Attribute mapping

By default Auth stores the user's email. To copy other SAML attributes into user_metadata, add a mapping as JSON:

{
  "keys": {
    "name": { "name": "displayName" },
    "first_name": { "name": "givenName" },
    "department": { "name": "department", "default": "unknown" }
  }
}

Each key is the field name in user_metadata, and name is the attribute the IdP sends. Attribute names differ between IdPs; Entra ID, for example, often uses long URIs such as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname.

Treat these values like any other user metadata: fine for display, but don't use them for authorization. See Roles, custom claims and RBAC.

Users and identities

• SSO users are ordinary Auth users with is_sso_user = true, plus an identity whose provider is sso:<provider id>.
• An SSO user is kept separate from a password or OAuth user with the same email. Plan which sign-in method each customer uses.
• Row Level Security works the same: auth.uid() is the SSO user's ID.
• To list a provider's users, query auth.identities in Studio's SQL editor: select user_id from auth.identities where provider = 'sso:<provider id>'.

Removing or changing a provider

Edit lets you change the domains, attribute mapping or metadata. Remove deletes the provider: its users can no longer sign in with SSO, but their accounts stay in your project.

Limits and notes

• SAML providers are managed in the dashboard. The Supabase CLI's supabase sso commands don't work with SupaHost, because they use Supabase's Management API. On your server, you can also call Auth's admin endpoint /auth/v1/admin/sso/providers with the service_role key.
• IdP-initiated sign-in (the user starts from their IdP's app dashboard) is supported. Users land on your Site URL, or on an allowed redirect URL if the IdP sends one as its RelayState.
• Encrypted SAML assertions aren't supported. Ask the IdP to sign assertions without encrypting them, which is the default for most IdPs.
• Each project has its own SAML signing certificate, which is included in the SP metadata.

Testing without a real IdP

Mock SAML is a free test IdP. Add a provider with the metadata URL https://mocksaml.com/api/saml/metadata and the domain example.com. Then call signInWithSSO({ domain: 'example.com' }) and sign in as any @example.com user. Remove the provider when you're done.