Single Sign-On with SAML 2.0 for Projects

Looking for guides on how to use Single Sign-On with the Supabase dashboard? Head on over to Enable SSO for Your Organization.

Supabase Auth supports enterprise-level Single Sign-On (SSO) for any identity providers compatible with the SAML 2.0 protocol. This is a non-exclusive list of supported identity providers:

• Google Workspaces (formerly known as G Suite)
• Okta, Auth0
• Microsoft Active Directory, Azure Active Directory, Microsoft Entra
• PingIdentity
• OneLogin

If you're having issues with identity provider software not on this list, open a support ticket.

Prerequisites

This guide requires the use of the Supabase CLI. Make sure you're using version v1.46.4 or higher. You can use supabase -v to see the currently installed version. You can use the supabase sso subcommands to manage your project's configuration.

SAML 2.0 support is disabled by default on Supabase projects. You can configure this on the Auth Providers page on your project.

Note that SAML 2.0 support is offered on plans Pro and above. Check the Pricing page for more information.

Terminology

The number of SAML and SSO acronyms can often be overwhelming. Here's a glossary which you can refer back to at any time:

• Identity Provider, IdP, or IDP
  An identity provider is a service that manages user accounts at a company or organization. It can verify the identity of a user and exchange that information with your Supabase project and other applications. It acts as a single source of truth for user identities and access rights.
• Service Provider, SP
  This is the software that is asking for user information from an identity provider. In Supabase, this is your project's Auth server.
• Assertion
  An assertion is a statement issued by an identity provider that contains information about a user.
• EntityID
  A globally unique ID (usually a URL) that identifies an Identity Provider or Service Provider across the world.
• NameID
  A unique ID (usually an email address) that identifies a user at an Identity Provider.
• Metadata
  An XML document that describes the features and configuration of an Identity Provider or Service Provider. It can be as a standalone document or as a URL.
• Certificate
  Supabase Auth (the Service Provider) trusts assertions from an Identity Provider based on the signature attached to the assertion.
• Assertion Consumer Service (ACS) URL
  This is one of the most important SAML URLs. It is the URL where Supabase Auth will accept assertions from an identity provider.
• Binding (Redirect, POST, or Artifact)
  This is a description of the way an identity provider communicates with Supabase Auth.
• RelayState
  State used by Supabase Auth to hold information about a request to verify the identity of a user.

Important SAML 2.0 information

Below is information about your project's SAML 2.0 configuration which you can share with the company or organization that you're trying to on-board.

Note that SLO (Single Logout) is not supported at this time with Supabase Auth. However, the URL is registered and advertised for when this does become available. SLO is a best-effort service, so we recommend considering Session Timebox or Session Inactivity Timeout instead to force your end-users to authenticate regularly.

Append ?download=true to the Metadata URL to download the Metadata XML file. This is useful in cases where the identity provider requires a file.

User accounts and identities

User accounts and identities created via SSO differ from regular (email, phone, password, social login...) accounts in these ways:

• No automatic linking. Each user account verified using a SSO identity provider will not be automatically linked to existing user accounts in the system.
• Emails are not necessarily unique. Given the behavior with no automatic linking, email addresses are no longer a unique identifier for a user account.
• Sessions may have a maximum duration. Depending on the configuration of the identity provider, a login session established with SSO may forcibly log out a user after a certain period of time.

Row Level Security

You can use information about the SSO identity provider in Row Level Security policies.

Here are some commonly used statements to extract SSO related information from the user's JWT:

• auth.jwt()#>>'{amr,0,method}'
• auth.jwt()#>>'{amr,0,provider}'
• auth.jwt()#>>'{user_metadata,iss}'

Managing SAML 2.0 connections

Once you've enabled SAML 2.0 support on your project via the Auth Providers page in the dashboard, you can use the Supabase CLI to add, update, remove and view information about identity providers.

Add a connection

To establish a connection to a SAML 2.0 Identity Provider (IdP) you will need:

• A SAML 2.0 Metadata XML file, or a SAML 2.0 Metadata URL pointing to an XML file
• (Optional) Email domains that the organization's IdP uses
• (Optional) Attribute mappings between the user properties of the IdP and the claims stored by Supabase Auth

You should obtain the SAML 2.0 Metadata XML file or URL from the organization whose IdP you wish to connect. Most SAML 2.0 Identity Providers support the Metadata URL standard.

Once you've obtained the SAML 2.0 Metadata XML file or URL you can establish a connection with your project's Supabase Auth server.

Understanding attribute mappings

When a user signs in using the SAML 2.0 Single Sign-On protocol, an XML document called the SAML Assertion is exchanged between the identity provider and Supabase Auth.

This assertion contains information about the user's identity and other authentication information.

Your project can be configured to recognize these attributes and map them into your project's database using a JSON structure. This process is called attribute mapping, and varies according to the configuration of the identity provider.

For example, the following JSON structure configures attribute mapping for the email and first_name user identity properties.

{
  "keys": {
    "email": {
      "name": "mail"
    },
    "first_name": {
      "name": "givenName"
    }
  }
}

Remove a connection

Once a connection to an identity provider is established, you can remove it.

Update a connection

You may wish to update settings about a connection to a SAML 2.0 identity provider.

Retrieving information about a connection

You can always obtain a list of all registered providers.

Pricing

$0.015 per SSO MAU. You are only charged for usage exceeding your subscription plan's quota.

Frequently asked questions

Publishing your application to an identity provider's marketplace

Many cloud-based identity providers offer a marketplace where you can register your application for easy on-boarding with customers.

Why do some users get: SAML assertion does not contain email address?

Identity providers do not have to send back an email address for the user, though they often do. Supabase Auth requires that an email address is present.

Accessing the private key used for SAML in your project

At this time it is not possible to extract the RSA private key used by your project's Supabase Auth server.

Is multi-tenant SSO with SAML supported?

Yes, Supabase supports multi-tenant Single Sign-On (SSO) using SAML 2.0.

Is multi-subdomain SSO with SAML supported?

Yes, also referred to as cross-origin authentication within the same site.

Why doesn't IdP-initiated SAML flow work with PKCE, and what's the alternative?

Traditional IdP-initiated SAML flows aren't compatible with PKCE (Proof Key for Code Exchange) because PKCE requires a code_challenge and code_verifier that are generated when your application initiates the authentication flow.