mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
a3e71ba888
Implements comprehensive IdP-initiated login flow support, enabling organizations to configure SSO without email domains and support multiple SAML apps under the same domain (e.g., Dev/Staging/Prod environments). - Add "Enable SP-initiated login" toggle to SSOConfig.tsx - IdP-initiated flow is now always available (default) - SP-initiated flow is opt-in with domain requirement - Clear in-UI documentation explaining both flows - Make domains optional (only required when SP-initiated enabled) - Add form validation: domains required only if SP-initiated is ON - Fix org-switching bug: form now resets when switching organizations - Add organization.slug to useEffect dependencies - Prevent stale SSO config data from previous org being displayed - **IdP-initiated flow**: Users start login from identity provider dashboard - No domain configuration required - Enables multiple SAML apps per domain - Recommended default for enterprises - **SP-initiated flow**: Users start login at supabase.com (opt-in) - Requires email domain configuration - Maintains backward compatibility - **Both flows**: Can be enabled simultaneously for flexible access - Organizations can now create separate SSO providers for Dev/Staging/Prod - Each environment = separate SAML app in IdP - All using same email domain (e.g., company.com) - Users access via different IdP app tiles - No domain conflicts or subdomain requirements - Add 4 pages to SSO sidebar menu in NavigationMenu.constants.ts: - Understanding Login Flows (existing, now visible) - Choosing a Login Flow (existing, now visible) - Multiple SSO Providers (NEW comprehensive guide) - Testing and Best Practices (existing, now visible) Create comprehensive guide covering: - Multi-environment patterns (Dev/Staging/Prod with same domain) - Team separation, migration, and acquisition scenarios - Step-by-step setup for domainless providers - User access management and IDP app assignment strategies - Configuration synchronization and best practices - Troubleshooting common multi-provider issues Major expansion of testing-best-practices.mdx: - Fix outdated assumptions (domains no longer always required) - Add comprehensive login flow testing section: - IdP-initiated testing (no domains) - SP-initiated testing (with domains) - Domainless provider testing (multi-environment pattern) - Enhance auto-join testing with 8 detailed test phases: - Idempotency testing (no duplicate memberships) - Domainless configuration testing - Re-enablement testing (works on every login) - Add SSO account restrictions testing section - Add safe provider deletion testing with 4 test scenarios - Reorganize final checklist into 6 categorized sections Update azure.mdx, gsuite.mdx, okta.mdx: - Remove all "(coming soon)" references - Add guidance recommending IdP-initiated for multi-environment setups - Clarify domains are optional for IdP-initiated flow - Link to new Multiple SSO Providers guide **Domain Handling:** - Domains now optional in SSO provider configuration - Backend: `z.array(...).optional().default([])` - UI: Domains only required when SP-initiated toggle is ON - Empty array sent to API when SP-initiated disabled **Login Flow Logic:** - IdP-initiated: Always available, uses SAML assertion directly - SP-initiated: Requires domain lookup, opt-in only - Both flows can coexist with same SSO provider **Multi-Provider Support:** - Each provider has unique ACS URL - No domain conflicts (IdP-initiated doesn't check domains) - Enables unlimited providers per email domain - **Simplifies SSO setup**: No domain configuration needed by default - **Enables multi-environment**: Dev/Staging/Prod under same domain - **Improves UX**: One-click login from IdP dashboard - **Maintains compatibility**: SP-initiated still available as opt-in - **Better documentation**: Comprehensive guides for all scenarios ## UI ### SSO Disabled <img width="742" height="329" alt="sso-disabled" src="https://github.com/user-attachments/assets/73387777-181c-4206-9798-36f0d0790e4e" /> ### SSO Enabled - IdP-inititated (DEFAULT) <img width="742" height="1059" alt="sso-enabled-idp" src="https://github.com/user-attachments/assets/c189e08f-7642-4183-8853-dd5150b8a191" /> ### SSO Enabled - SP-intitiated <img width="727" height="1366" alt="sso-enabled-sp" src="https://github.com/user-attachments/assets/be5ad6dc-4803-446b-ae02-9edcbb5f42cd" /> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive guides for SSO login flow selection, testing best practices, and configuring multiple providers * Updated provider-specific setup documentation (Okta, Azure, Google Workspace) with refined workflows and testing recommendations * **New Features** * Enhanced SSO configuration interface with SP-initiated login toggle and improved email domain management for flexible authentication flows <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Chris Stockton <chris.stockton@supabase.io> Co-authored-by: Chris Chinchilla <chris.ward@supabase.io> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
268 lines
9.6 KiB
Plaintext
268 lines
9.6 KiB
Plaintext
---
|
|
title: 'Understanding SSO Login Flows'
|
|
description: 'Learn about IdP-initiated and SP-initiated SSO login flows and when to use each approach.'
|
|
---
|
|
|
|
When configuring SSO for your organization, you can choose between two different login flows: **identity provider (IdP)-initiated** and **service provider (SP)-initiated**. Understanding the difference helps you provide the best experience for your users.
|
|
|
|
<Admonition type="tip" label="Quick decision guide">
|
|
|
|
Most enterprises use IdP-initiated flow for its simplicity and better user experience. Enable SP-initiated only if you need users to start their login journey at supabase.com.
|
|
|
|
See our [Choosing the Right Login Flow guide](/docs/guides/platform/sso/choosing-login-flow) for use case examples.
|
|
|
|
</Admonition>
|
|
|
|
## Overview of login flows
|
|
|
|
### IdP-initiated (Identity Provider Initiated)
|
|
|
|
With IdP-initiated flow, users start their login journey from your identity provider (Okta, Azure AD, Google Workspace, etc.) and are directly authenticated into Supabase.
|
|
|
|
**User experience:**
|
|
|
|
1. User opens their identity provider dashboard (e.g., Okta homepage, Azure MyApps)
|
|
2. User clicks the Supabase app tile or bookmark
|
|
3. User is immediately logged into Supabase (if already authenticated with IdP)
|
|
|
|
**Key characteristics:**
|
|
|
|
- ✅ Simpler user experience - one click from IdP
|
|
- ✅ No domain configuration required
|
|
- ✅ Works automatically once SSO is enabled
|
|
- ✅ Better for intranet portals and employee app catalogs
|
|
- ✅ Default behavior in Supabase
|
|
|
|
### SP-initiated (Service Provider Initiated)
|
|
|
|
With SP-initiated flow, users start at supabase.com, enter their email address, and are redirected to your identity provider for authentication.
|
|
|
|
**User experience:**
|
|
|
|
1. User visits supabase.com and clicks "Sign in with SSO"
|
|
2. User enters their email address
|
|
3. User is redirected to their identity provider
|
|
4. After authenticating, user is redirected back to Supabase
|
|
|
|
**Key characteristics:**
|
|
|
|
- ✅ Familiar flow for users who bookmark supabase.com
|
|
- ✅ Supports domain-based automatic IdP routing
|
|
- ⚠️ Requires configuring email domains
|
|
- ⚠️ More steps in the login process
|
|
|
|
## Choosing between flows
|
|
|
|
### When to use IdP-initiated (recommended)
|
|
|
|
**Best for:**
|
|
|
|
- Organizations with established identity provider workflows
|
|
- Users who primarily access apps through their IdP dashboard
|
|
- Multiple SAML apps per domain (Dev, Staging, Prod environments)
|
|
- Simplifying user onboarding
|
|
|
|
**Common scenarios:**
|
|
|
|
- "Our team accesses all tools through Okta tiles"
|
|
- "We want the simplest possible login experience"
|
|
- "We need separate Dev and Prod SAML apps under the same domain"
|
|
- "Users should never need to remember supabase.com"
|
|
|
|
### When to use SP-initiated
|
|
|
|
**Best for:**
|
|
|
|
- Organizations where users bookmark supabase.com directly
|
|
- Migrating from password-based authentication
|
|
- Users unfamiliar with identity provider dashboards
|
|
|
|
**Common scenarios:**
|
|
|
|
- "Some users bookmark supabase.com and expect to start there"
|
|
- "We're transitioning from password auth to SSO"
|
|
- "Users need a consistent login page across all tools"
|
|
- "We want domain-based automatic IdP selection"
|
|
|
|
### When to enable both flows
|
|
|
|
You can enable both flows simultaneously to support different user preferences.
|
|
|
|
**Best for:**
|
|
|
|
- Large organizations with diverse user needs
|
|
- Gradual SSO migration with mixed authentication
|
|
- Supporting both technical and non-technical users
|
|
|
|
## Configuring login flows
|
|
|
|
### Enabling IdP-initiated flow (default)
|
|
|
|
IdP-initiated flow is automatically enabled when you configure SSO. No additional steps required.
|
|
|
|
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) section of the dashboard
|
|
2. Enable "Single Sign-On"
|
|
3. Configure your identity provider metadata and attribute mapping
|
|
4. Save your configuration
|
|
|
|
Users can now access Supabase through your IdP's app catalog.
|
|
|
|
<Admonition type="note" label="Domain configuration optional">
|
|
|
|
With IdP-initiated flow, you don't need to configure email domains. Your identity provider handles all authentication routing.
|
|
|
|
</Admonition>
|
|
|
|
### Enabling SP-initiated flow
|
|
|
|
To enable SP-initiated flow, you need to configure email domains:
|
|
|
|
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) 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
|
|
|
|
#### Email domain requirements
|
|
|
|
- At least one domain required when SP-initiated is enabled
|
|
- Domains must be verified through your identity provider
|
|
- Multiple domains supported (e.g., `company.com`, `subsidiary.com`)
|
|
- Users with matching email domains will be routed to your IdP
|
|
|
|
<Admonition type="caution" label="Domain restrictions apply">
|
|
|
|
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 you configure it in your IdP).
|
|
|
|
</Admonition>
|
|
|
|
### Switching between flows
|
|
|
|
You can change login flow configuration at any time:
|
|
|
|
#### To switch from SP-initiated to IdP-only
|
|
|
|
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) section of the dashboard
|
|
2. Toggle **Enable SP-initiated login** to "OFF"
|
|
3. Save changes
|
|
|
|
Existing users can continue signing in via IdP-initiated flow.
|
|
|
|
#### To switch from IdP-only to SP-initiated
|
|
|
|
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) section of the dashboard
|
|
2. Toggle **Enable SP-initiated login** to "ON"
|
|
3. Add required email domains
|
|
4. Save changes
|
|
|
|
## Technical details
|
|
|
|
### How IdP-initiated flow works
|
|
|
|
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 required** - The IdP assertion contains all necessary user information.
|
|
|
|
### How SP-initiated flow works
|
|
|
|
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.
|
|
|
|
## Multiple SAML apps per domain
|
|
|
|
One of the key advantages of IdP-initiated flow is supporting multiple SAML applications under the same domain.
|
|
|
|
### The problem with SP-initiated only
|
|
|
|
Many enterprises need separate SAML apps for different environments:
|
|
|
|
- Development SAML app
|
|
- Staging SAML app
|
|
- Production SAML app
|
|
|
|
**With SP-initiated flow only:** Each SAML app requires a unique domain. You'd need:
|
|
|
|
- `dev.company.com`
|
|
- `staging.company.com`
|
|
- `prod.company.com`
|
|
|
|
This is often impractical since all employees use `company.com` email addresses.
|
|
|
|
### The solution with IdP-initiated flow
|
|
|
|
**With IdP-initiated flow:** All SAML apps can use the same domain (`company.com`) because:
|
|
|
|
- Users access each app through different IdP tiles/bookmarks
|
|
- No domain-based routing is needed
|
|
- Each SAML app has its own unique ACS URL and metadata
|
|
|
|
#### Configuration in your IdP
|
|
|
|
- Create "Supabase Dev" SAML app → Points to dev org's ACS URL
|
|
- Create "Supabase Staging" SAML app → Points to staging org's ACS URL
|
|
- Create "Supabase Production" SAML app → Points to prod org's ACS URL
|
|
|
|
Users click the appropriate tile for the environment they need.
|
|
|
|
<Admonition type="tip">
|
|
|
|
This is the recommended approach for enterprises with multiple environments. Configure each environment as IdP-initiated only (no domains needed).
|
|
|
|
</Admonition>
|
|
|
|
## Common questions
|
|
|
|
### Can you use both flows simultaneously?
|
|
|
|
Yes! Enable SP-initiated login and configure domains. IdP-initiated flow continues to work automatically.
|
|
|
|
### What happens when you don't configure domains?
|
|
|
|
Without domains, only IdP-initiated flow is available. Users cannot start their login at supabase.com.
|
|
|
|
### Does the IdP require configuration?
|
|
|
|
For **IdP-initiated flow:** Configure the Supabase ACS URL and entity ID in your IdP. See our provider-specific guides:
|
|
|
|
- [Google Workspace](/docs/guides/platform/sso/gsuite)
|
|
- [Azure Active Directory](/docs/guides/platform/sso/azure)
|
|
- [Okta](/docs/guides/platform/sso/okta)
|
|
|
|
For **SP-initiated flow:** Same configuration, but also ensure your IdP accepts SAML requests from Supabase.
|
|
|
|
### What happens if a user tries SP-initiated with no matching domain?
|
|
|
|
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).
|
|
|
|
### Can you disable SP-initiated flow after enabling it?
|
|
|
|
Yes, toggle it off at any time. Existing users can continue using IdP-initiated flow.
|
|
|
|
### Which flow is more secure?
|
|
|
|
Both flows are equally secure when properly configured. Security depends on:
|
|
|
|
- Strong identity provider authentication policies
|
|
- Certificate management and rotation
|
|
- Attribute mapping configuration
|
|
- Regular security audits
|
|
|
|
See our [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide for security recommendations.
|
|
|
|
## Next steps
|
|
|
|
- **Choose your login flow:** See [Choosing the Right Login Flow](/docs/guides/platform/sso/choosing-login-flow)
|
|
- **Configure your provider:** Follow our [provider-specific guides](/docs/guides/platform/sso#supported-providers)
|
|
- **Test thoroughly:** Review [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices)
|
|
- **Enable auto-join:** Configure [auto-join settings](/docs/guides/platform/sso#key-configuration-options) for seamless onboarding
|