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).
Availability
Section titled “Availability”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.
Set up
Section titled “Set up”-
Open Platform services → Auth → SSO and turn SAML on. The page shows what the IdP needs from you:
IdP field Value Entity ID / Audience https://<ref>.us-east.databasezy.com:8443/auth/v1/sso/saml/metadataACS (reply) URL https://<ref>.us-east.databasezy.com:8443/auth/v1/sso/saml/acsMetadata URL the entity ID (our signing certificate is in it) Name ID email address (recommended) or a persistent id -
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" } } }}' -
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
Section titled “Attribute mapping”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'.
What is checked
Section titled “What is checked”- 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
Conditionstime window and the audience (your entity ID). InResponseTomust match the request your project sent; each sign-in request (relay state) is single use and expires afterrelay_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_failedwith 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.
Limits
Section titled “Limits”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.
Bindings
Section titled “Bindings”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):
signInWithSSOreturns the IdP URL with the request and its signature in the query string. - HTTP-POST when the IdP offers only that binding:
signInWithSSOreturnshttps://<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 strictContent-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.