SSO users see only invited or auto-joined organizations
SSO users will only see organizations/projects they have been invited to or auto-joined into.
auth
381 notes in this subject, read out of this brain and free to use. This is page 3 of 7.
SSO and non-SSO accounts with same email are separate
If an SSO user with email alice@foocorp.com attempts to sign in with a GitHub account that uses the same email, a separate Supabase account is created and will not be linked to the SSO user's account. SSO and non-SSO accounts with the same email are treated as separate accounts.
SSO users cannot update or reset password
An SSO user will not be able to update or reset their password since the company administrator manages their access via the identity provider.
SSO user default organization
Every SSO user has an organization created by default. They can create as many projects as they want.
SSO auto-join default role recommendation
When auto-join is enabled, the default role for new SSO users should be Developer, following the principle of least privilege. Users can be promoted individually as needed.
SSO auto-join applies on every login
When auto-join is enabled, SSO-authenticated users are automatically added to the organization on every login, not only on first signup. This makes it safe to test SSO before enabling this feature.
SSO auto-join disabled by default
By default, the auto-join setting is disabled. Users logging in via SSO will not be added to the organization automatically. The recommended workflow is to start with auto-join disabled to test SSO configuration, then enable it once SSO login is working correctly.
Google Workspace SSO configuration propagation delay
Changes to user access configuration in Google Workspace sometimes take a while to propagate across Google's systems. Wait at least 15 minutes before testing changes.
Certificate expiration management for SSO
The IdP metadata certificate must have at least 1 year before expiration. Set a calendar reminder 30 days before certificate expiration date. When the certificate is renewed, download the new metadata file and update it in Supabase SSO settings. Expired certificates are a common cause of SSO sign-in failures.
SAML attribute mapping requirement
A mapping from Primary email to the email attribute is required in SAML attribute configuration. Other mappings are optional and configurable depending on Google Workspace setup.
Google Workspace SAML service provider configuration values
When configuring Google Workspace SAML app, use these service provider details: ACS URL is https://alt.supabase.io/auth/v1/sso/saml/acs, Entity ID is https://alt.supabase.io/auth/v1/sso/saml/metadata, Start URL is https://supabase.com/dashboard, Name ID format is PERSISTENT, and Name ID should map to Basic Information > Primary email.
Google Workspace SSO availability
SSO with Google Workspace is only available on the Team and Enterprise Plans.
Single production organization configuration
For a single Supabase organization serving your entire company, use IdP-initiated flow only. Enable SSO in the organization, leave 'Enable SP-initiated login' OFF, configure identity provider metadata, and create a Supabase app tile in your IdP. This is the simplest possible setup requiring no domain configuration.
Starting SSO implementation approach
When uncertain which configuration to use, start with IdP-initiated only as it is the simplest and works for most cases. Test with a small group of users, gather feedback on user experience, enable SP-initiated if users request it, and monitor usage to see which flow is preferred.
Multiple environments with single domain strategy
When you need separate Supabase organizations for Dev, Staging, and Production but all employees use the same company email domain, use IdP-initiated flow only. Create separate SAML apps in your IdP for each environment, each pointing to the corresponding org's ACS URL. Leave 'Enable SP-initiated login' OFF in each Supabase organization. Users access each environment by clicking different app tiles in their IdP dashboard (e.g., 'Supabase Dev', 'Supabase Staging', 'Supabase Production').
Account linking pitfall with mixed authentication
SSO and non-SSO accounts with the same email are treated as separate accounts. An employee with alice@company.com will have two accounts if they join via SSO and previously joined via password authentication. This must be communicated clearly to users about which authentication method they should use.
IdP-initiated vs SP-initiated SSO flows
IdP-initiated is the default SSO flow where users start login from their identity provider dashboard. It requires no domain configuration and works for most enterprise use cases. SP-initiated flow allows users to start login at supabase.com by enabling the 'Enable SP-initiated login' toggle and configuring email domains. Both flows can be enabled simultaneously to support users with different preferences.
Safely changing SSO flow configuration
SSO login flow configuration can be safely changed at any time with no migration required and changes take effect immediately. Adding SP-initiated to IdP-only: toggle 'Enable SP-initiated login' ON, add required domains, test with existing users. No disruption to IdP-initiated flow occurs. Removing SP-initiated: toggle 'Enable SP-initiated login' OFF, domains are preserved for later re-enabling, IdP-initiated continues working. Users who bookmarked supabase.com will need to use IdP tiles instead.
Testing SSO configuration
Test all configured flows thoroughly: For IdP-initiated, click the app tile in IdP and verify redirect to Supabase. For SP-initiated, go to supabase.com/sign-in-sso, enter email, and verify IdP redirect. Test auto-join with new user accounts. Test domain restrictions by trying a non-matching domain which should fail for SP-initiated flow.
SSO login flow decision reference table
Use case configuration guide: Multiple environments (Dev/Staging/Prod) uses IdP-initiated only with no domains required. Single production org uses IdP-initiated only with no domains required. Users bookmark supabase.com use both flows with domains required. Migrating from passwords use both flows with domains required. Multiple email domains use both flows with all domains required. Customer-specific SSO (SaaS) defaults to IdP-initiated with SP-initiated optional and per-customer domains. Mixed authentication uses both flows with domains required.
Mixed authentication with SSO and non-SSO users
When some users authenticate via SSO (employees) and others use password or social auth (contractors, external partners) in the same organization, enable both flows with careful planning. Configure employee email domain(s), use SSO-required invitations for employees, and non-SSO invitations for contractors. Consider disabling auto-join to control membership. Note: SSO and non-SSO accounts with the same email are treated as separate accounts, so communicate clearly which authentication method each user should use.
SaaS platform with customer-specific SSO
For a SaaS product where each customer has their own organization and identity provider, default each customer to IdP-initiated flow (simplest setup) and enable SP-initiated only if the customer specifically requests it. Document both options in customer onboarding and let customers choose based on their workflow.
Multiple subsidiaries with different email domains
When a parent company and subsidiaries (each with different email domains like parent.com, sub1.com, sub2.com) share the same Supabase organization, enable SP-initiated flow with multiple domains. Toggle 'Enable SP-initiated login' ON and add all domains. Configure the identity provider to accept all domains. Users with any configured domain can access the organization with automatic routing based on email domain.
Supporting users who bookmark supabase.com
When users frequently bookmark supabase.com directly and you want to support starting login from Supabase, enable both IdP-initiated and SP-initiated flows. Toggle 'Enable SP-initiated login' ON and add your email domain(s) (e.g., company.com). This supports both users who start at supabase.com and users who prefer IdP tiles.
Migrating from password authentication to SSO
When transitioning from password-based login to SSO, enable both IdP-initiated and SP-initiated flows. Ensure at least one non-SSO owner account exists before enabling SSO. Start with auto-join disabled, test with a small group, then enable auto-join after confirmation. Migration path: Week 1 enable both flows and announce availability; Week 2-4 monitor usage and troubleshoot; Month 2+ promote IdP tiles and consider disabling SP-initiated if usage drops.
Testing SSO configuration before rollout
Before rolling out SSO to an organization, thorough testing is strongly recommended. For Okta implementations, consider testing the SSO configuration in an Okta sandbox environment first before applying to production. Start with auto-join disabled to test the basic SSO configuration, then enable auto-join once SSO login is working correctly.
SSO auto-join feature behavior
By default, SSO auto-join is disabled and users logging in via SSO are not added to the organization automatically. When enabled, SSO-authenticated users are automatically added to the organization on every login, not only on first signup. The feature allows setting a default role for new users, with Developer recommended as the default (principle of least privilege).
SSO domain configuration rules
When configuring SSO domains in the Supabase dashboard, enter one or more domains associated with user email addresses. These domains determine which users are eligible to sign in via SSO. Multiple email domains can be added (for example, supabase.com for staff and supabase.io for contractors). Public domains like gmail.com and yahoo.com are not permitted.
Okta IdP metadata URL format
The IdP metadata URL obtained from Okta typically has the structure: https://<okta-org>.okta.com/apps/<app-id>/sso/saml/metadata. This URL is found in the SAML Signing Certificates section on the Sign On tab, by selecting a SHA-2 row with Active status, clicking Actions, and choosing View IdP Metadata.
Okta email attribute statement requirement
A mapping from `email` to `user.email` is required when configuring attribute statements in Okta. Other mappings are optional and configurable depending on your Okta setup.
Okta SAML 2.0 configuration values for Supabase
When setting up SAML 2.0 with Okta for Supabase, use these exact values: Single sign-on URL: https://alt.supabase.io/auth/v1/sso/saml/acs (also use for Recipient URL and Destination URL); Audience URI (SP Entity ID): https://alt.supabase.io/auth/v1/sso/saml/metadata; Default RelayState: https://supabase.com/dashboard; Name ID format: EmailAddress; Application username: Email; Update application username on: Create and update.
SSO with Okta feature availability
Single sign-on using Okta is only available on the Team and Enterprise Plans. This feature is not available on free or standard plans.
Multi-environment SSO setup recommendation
For multi-environment setups (Dev/Staging/Prod), it is recommended to use IdP-initiated flow with multiple SAML apps under the same domain rather than domain-based routing. Each SSO provider can be configured with different email domains.
Switching from IdP-only to SP-initiated SSO
To switch from IdP-only to SP-initiated: (1) Navigate to the SSO settings section of the dashboard, (2) Toggle 'Enable SP-initiated login' to 'ON', (3) Add required email domains, (4) Save changes.
Email domain requirements for SP-initiated flow
When SP-initiated flow is enabled, at least one email domain is required. Domains must be verified through your identity provider. Multiple domains are supported (e.g., company.com, subsidiary.com). Only users with email addresses matching your configured domains can use SP-initiated login. Users with other domains cannot sign in via SSO at supabase.com but can still use IdP-initiated flow if configured in the IdP.
Configuring IdP-initiated SSO flow
IdP-initiated flow is automatically enabled when you configure SSO and requires no additional steps. To enable it: (1) Navigate to the SSO settings section of the dashboard, (2) Enable 'Single Sign-On', (3) Configure your identity provider metadata and attribute mapping, (4) Save your configuration. Domain configuration is optional with IdP-initiated flow; the identity provider handles all authentication routing.
Configuring SP-initiated SSO flow
To enable SP-initiated flow: (1) Navigate to the SSO settings section of the dashboard, (2) Enable 'Single Sign-On', (3) Toggle 'Enable SP-initiated login' to 'ON', (4) Add one or more email domains (e.g., yourcompany.com), (5) Configure your identity provider metadata and attribute mapping, (6) Save your configuration. At least one domain is required when SP-initiated is enabled, and domains must be verified through your identity provider.
SP-initiated SSO flow overview
SP-initiated (Service Provider Initiated) flow allows users to start at supabase.com, enter their email address, and be redirected to their identity provider for authentication. The user visits supabase.com and clicks 'Sign in with SSO', enters their email address, is redirected to their identity provider, and after authenticating is redirected back to Supabase. This flow supports users who bookmark supabase.com directly and supports domain-based automatic IdP routing, but requires configuring email domains and involves more steps in the login process.
IdP-initiated SSO flow overview
IdP-initiated flow allows users to start their login journey from their identity provider (Okta, Azure AD, Google Workspace, etc.) and are directly authenticated into Supabase. The user opens their identity provider dashboard (e.g., Okta homepage, Azure MyApps), clicks the Supabase app tile or bookmark, and is immediately logged into Supabase if already authenticated with the IdP. This flow has simpler user experience, requires no domain configuration, works automatically once SSO is enabled, and is better for intranet portals and employee app catalogs. IdP-initiated is the default behavior in Supabase.
Enabling both SSO flows simultaneously
Both IdP-initiated and SP-initiated flows can be enabled simultaneously to support different user preferences. This is best for large organizations with diverse user needs, gradual SSO migration with mixed authentication, and when supporting both technical and non-technical users.
When to use IdP-initiated SSO flow
IdP-initiated flow is best for organizations with established identity provider workflows where users primarily access apps through their IdP dashboard, scenarios with multiple SAML apps per domain (Dev, Staging, Prod environments), and when simplifying user onboarding. It is recommended for the majority of enterprises for its simplicity and better user experience.
SSO security comparison between flows
Both IdP-initiated and SP-initiated flows are equally secure when properly configured. Security depends on strong identity provider authentication policies, certificate management and rotation, attribute mapping configuration, and regular security audits.
SP-initiated SSO error when no matching domain
When a user tries SP-initiated login with no matching email domain configured, they receive an error message indicating no SSO provider found for their email domain. They can still sign in using password or social auth if they have a non-SSO account.
Disabling SP-initiated flow after enabling it
SP-initiated flow can be disabled at any time by toggling it off in the SSO settings. Existing users can continue using IdP-initiated flow.
When to use SP-initiated SSO flow
SP-initiated flow is best for organizations where users bookmark supabase.com directly, when migrating from password-based authentication, and when users are unfamiliar with identity provider dashboards. It is also appropriate when users need a consistent login page across all tools or when the organization wants domain-based automatic IdP selection.
IdP configuration for SP-initiated SSO
For SP-initiated flow, configure the same settings as IdP-initiated (Supabase ACS URL and entity ID), but also ensure your IdP accepts SAML requests from Supabase.
IdP configuration for IdP-initiated SSO
For IdP-initiated flow, configure the Supabase ACS URL and entity ID in your identity provider. Provider-specific guides are available for Google Workspace, Azure Active Directory, and Okta.
Behavior when no domains configured for SSO
Without domains configured, only IdP-initiated flow is available. Users cannot start their login at supabase.com.
Multiple SAML apps problem with SP-initiated only
With SP-initiated flow only, each SAML app requires a unique domain. Enterprises needing separate SAML apps for different environments would need separate domains like dev.company.com, staging.company.com, and prod.company.com, which is often impractical since all employees use the same company.com email addresses.
Multiple SAML apps per domain with IdP-initiated flow
IdP-initiated flow supports multiple SAML applications under the same domain, which solves the problem of needing separate environments (Development, Staging, Production). With IdP-initiated flow, all SAML apps can use the same domain (e.g., company.com) because users access each app through different IdP tiles/bookmarks and no domain-based routing is needed. Each SAML app has its own unique ACS URL and metadata. This is configured in the IdP by creating separate SAML apps (e.g., 'Supabase Dev', 'Supabase Staging', 'Supabase Production') each pointing to the respective environment's ACS URL, and users click the appropriate tile for the environment they need.
How IdP-initiated SSO flow works technically
IdP-initiated flow works as follows: (1) User clicks app tile in identity provider, (2) IdP generates SAML assertion and POSTs to Supabase ACS URL, (3) Supabase validates assertion and creates session, (4) User is redirected to Supabase dashboard. No domain lookup is required because the IdP assertion contains all necessary user information.
How SP-initiated SSO flow works technically
SP-initiated flow works as follows: (1) User enters email at supabase.com/sign-in-sso, (2) Supabase matches email domain to configured SSO provider, (3) Supabase generates SAML request and redirects to IdP, (4) IdP authenticates user and generates SAML assertion, (5) IdP POSTs assertion to Supabase ACS URL, (6) Supabase validates assertion and creates session. Domain matching is critical; without matching domains, users cannot complete SP-initiated flow.
Troubleshooting: SP-initiated with multiple organizations same domain
Symptom: With SP-initiated enabled and same domain in multiple organizations, users get routed to unexpected organization. Cause: SP-initiated routing uses first matching provider. Solution: Recommended - Switch to IDP-initiated only (disable SP-initiated), remove domain configuration from all but one organization, provide clear IDP app tiles for explicit routing, document which organization users should access via SP-initiated.
Troubleshooting: Users accessing wrong SSO environment
Symptom: User clicks Supabase Prod tile but sees dev environment. Causes: Metadata configured incorrectly or swapped, ACS URL points to wrong organization, user bookmarked wrong organization. Solution: Verify ACS URL in IDP app configuration, compare metadata in Supabase SSO settings, check organization slug matches expected environment, have user clear browser cookies and retry, verify user clicking correct app tile.
Migration from single to multiple SSO providers phases
Phase 1 (Planning): Decide which pattern (environments, teams, etc.), document new organization structure, identify users per environment, plan communication. Phase 2 (Create organizations): Create additional Supabase organizations, configure projects, migrate data if needed. Phase 3 (Configure providers): Create additional SAML apps in IDP, configure SSO in each organization, start with auto-join disabled, test with small group. Phase 4 (Migrate users): Communicate changes, assign users to appropriate IDP apps, test access, enable auto-join if desired. Phase 5 (Decommission): Migrate all users, verify none depend on old, disable old provider, monitor, delete after verification.
SSO migration workflow phases
When migrating from one identity provider to another, use four phases: Phase 1 (Dual configuration) - Configure new IDP as additional provider while keeping existing IDP active, test with small group. Phase 2 (Gradual rollout) - Migrate users in batches, update app tile assignments, monitor. Phase 3 (Cutover) - Move all users to new IDP, verify none depend on old, disable old provider. Phase 4 (Cleanup) - After 1-2 weeks verification, delete old provider. Always maintain at least one non-SSO owner account during migration.
Troubleshooting: Auto-join adding users to wrong organization
Symptom: User joins dev environment when should join production. Cause: User clicked wrong app tile with auto-join enabled. Prevention: Disable auto-join in production (explicit invitations only), use clear app tile naming, document tile-to-environment mapping, consider using different IDP groups. Remediation: Remove user from incorrect organization, send explicit invitation to correct organization, educate on correct tile, consider disabling auto-join.
Troubleshooting: Users don't see expected SSO app tiles
Symptom: User cannot find Supabase Staging tile in IDP dashboard. Causes: User not assigned to app in IDP, app not deployed/published, user looking in wrong place. Solution: Verify app assignment in IDP admin console, check app published/active, confirm user logged out and back into IDP, verify user checking correct IDP portal.
Recommended pattern for multiple SSO providers
Configure each environment as IdP-initiated only with no domains. Users access each environment through different app tiles in their identity provider.
Troubleshooting: SSO configuration drift between environments
Symptom: SSO works in dev but fails in staging or production. Causes: Attribute mappings differ between providers, certificate expired in one environment but not others, domain configuration inconsistent if using SP-initiated. Solution: Compare SSO configurations side-by-side, check attribute mappings identical, verify certificate expiration dates, test with same user across environments, review IDP audit logs for authentication failures.