Skip to content

Platform

SAML single sign-on

Tested with:supabase-js 2 · @supabase/auth-js 2.117

Your project acts as a SAML 2.0 service provider for its own users. Your app calls Supabase’s supabase.auth.signInWithSSO({ domain }) (or { providerId }) and the user signs in at their company’s identity provider (IdP).

SAML SSO for your app’s users is an add-on on the Team plan (turning it on for a project adds the add-on) and included on Enterprise. On other plans, turning it on answers 402 with the problem type https://databasezy.com/problems/plan_limit. The add-on price is on the pricing page.

On Team the add-on is billed per project by the hour (usage line SAML SSO for app auth, meter app_auth_saml_hours, $75 a month per project) from the moment SAML and the project’s app auth are both on until either is turned off or the project is deleted. Enterprise is never charged for it.

  1. Open Platform services → Auth → SSO and turn SAML on. The page shows what the IdP needs from you:

    IdP fieldValue
    Entity ID / Audiencehttps://<ref>.us-east.databasezy.com:8443/auth/v1/sso/saml/metadata
    ACS (reply) URLhttps://<ref>.us-east.databasezy.com:8443/auth/v1/sso/saml/acs
    Metadata URLthe entity ID (our signing certificate is in it)
    Name IDemail address (recommended) or a persistent id
  2. Create the application at your IdP with those values, then add it as a provider: paste the IdP’s metadata XML or its metadata URL (fetched once, https on a public host only), and list the email domains that should use it.

    shell
    zb api POST /v1/orgs/{org}/projects/<project-id>/auth/sso/providers -d '{
    "name": "Acme Okta",
    "metadata_url": "https://acme.okta.com/app/abc123/sso/saml/metadata",
    "domains": ["acme.com"],
    "attribute_mapping": { "keys": { "email": { "name": "email" }, "department": { "name": "dept" } } }
    }'
  3. Sign in from your app:

    app/login.ts
    const { data } = await supabase.auth.signInWithSSO({ domain: "acme.com" });
    location.assign(data.url); // the IdP, with a signed AuthnRequest

After the IdP posts back, the user lands on your redirect URL with a session (or ?code= with the PKCE flow, exchanged by exchangeCodeForSession). The user’s identity is the Name ID under that provider (sso:<provider id>); the email comes from the mapped email attribute or an email-format Name ID. An SSO user’s email, phone and password belong to the IdP and cannot be changed in your app (user_sso_managed).

attribute_mapping.keys maps claims to SAML attributes: {"name": "..."} (or "names" for the first present of several), "array": true for multi-valued attributes and "default" for a fixed value. Mapped claims are stored in the user’s metadata as custom_claims (with the IdP’s iss and the Name ID as sub), so policies read them from auth.jwt() -> 'user_metadata' -> 'custom_claims'.

  • The assertion (or the whole response) must be signed with one of the IdP’s certificates from its metadata; unsigned or altered assertions are refused. Encrypted assertions are decrypted with your project’s SP key.
  • Issuer, destination and recipient, the bearer confirmation and its expiry, the Conditions time window and the audience (your entity ID).
  • InResponseTo must match the request your project sent; each sign-in request (relay state) is single use and expires after relay_state_validity (600 s).
  • Assertion ids are remembered until they expire: a replayed response is refused.
  • Every refusal is written to the auth audit log (login_failed with the reason); signature, audience, time-window, InResponseTo, replay and unknown-issuer problems are also security events.
  • IdP-initiated sign-in (a tile in the IdP’s dashboard) is off unless you set allow_idp_initiated; the replay and signature checks still apply.

Up to 25 identity providers per project and 50 domains per provider; a domain belongs to one provider. Providers are managed in the console and the management API; GoTrue’s POST/PUT/DELETE /auth/v1/admin/sso/providers are read-only here.

Your project sends a signed AuthnRequest with the binding the IdP’s metadata offers for its SingleSignOnService:

  • HTTP-Redirect when the metadata lists it (Okta, Entra ID, Google Workspace, OneLogin, JumpCloud and Keycloak do): signInWithSSO returns the IdP URL with the request and its signature in the query string.
  • HTTP-POST when the IdP offers only that binding: signInWithSSO returns https://<ref>.<region>.databasezy.com:8443/auth/v1/sso/saml/request?relay_state=..., a page of your project’s auth endpoint that posts the request (signed with an enveloped XML signature) to the IdP with an auto-submitting form. The page sends a strict Content-Security-Policy (its one script runs under a per-response nonce, forms may only post to https), cannot be framed, is not cached, and stops working once the sign-in completes or the relay state expires (relay_state_validity). supabase-js follows the URL like any other, so app code does not change.