PublicArchive/supabase
2
0
Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-05-06 08:56:46 -04:00
Code Issues Packages Projects Releases Wiki Activity

feat(sso): add IdP-initiated login support with optional domains (#44033)

Browse Source 
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>
This commit is contained in:
Chris Stockton
2026-04-20 09:47:35 -07:00
committed by GitHub
parent 667be50982
commit a3e71ba888
14 changed files with 2412 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+16
View File
@@ -2588,12 +2588,28 @@ export const platform: NavMenuConstant = {
enabled: fullPlatformEnabled,
items: [
{ name: 'Overview', url: '/guides/platform/sso' as `/${string}` },
{
name: 'Understanding Login Flows',
url: '/guides/platform/sso/login-flows' as `/${string}`,
},
{
name: 'Choosing a Login Flow',
url: '/guides/platform/sso/choosing-login-flow' as `/${string}`,
},
{ name: 'SSO with Azure AD', url: '/guides/platform/sso/azure' },
{
name: 'SSO with Google Workspace',
url: '/guides/platform/sso/gsuite' as `/${string}`,
},
{ name: 'SSO with Okta', url: '/guides/platform/sso/okta' },
{
name: 'Multiple SSO Providers',
url: '/guides/platform/sso/multiple-providers' as `/${string}`,
},
{
name: 'Testing and Best Practices',
url: '/guides/platform/sso/testing-best-practices' as `/${string}`,
},
],
},
],
apps/docs/content/guides/platform/sso.mdx
+101 -12
View File
@@ -19,21 +19,64 @@ Supabase currently provides SAML SSO for [Team and Enterprise Plan customers](/p
## Supported providers
Supabase supports practically all identity providers that support the SAML 2.0 SSO protocol. We've prepared these guides for commonly used identity providers to help you get started. If you use a different provider, our support stands ready to support you.
Supabase supports practically all identity providers (IdP) that support the SAML 2.0 SSO protocol. These guides cover commonly used identity providers to help you get started. If you use a different provider, contact support.
- [Google Workspaces (formerly G Suite)](/docs/guides/platform/sso/gsuite)
- [Azure Active Directory](/docs/guides/platform/sso/azure)
- [Okta](/docs/guides/platform/sso/okta)
Once configured, you can update your settings anytime via the [SSO tab](/dashboard/org/_/sso) under **Organization Settings**.
Once configured, you can update your settings anytime from [the **SSO** section](/dashboard/org/_/sso) of the dashboard under **Organization Settings**.
![SSO Example](/docs/img/sso-dashboard-enabled.png)
![SSO Example](/docs/img/sso-dashboard-enabled-idp.png)
<Admonition type="tip" label="Testing your SSO configuration">
After configuring your SSO provider, thorough testing is essential. See our [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide for:
- Step-by-step testing instructions
- Troubleshooting common issues
- Security best practices
- Pre-launch checklist
</Admonition>
## Choosing your login flow
Supabase supports two SSO login flows: **IdP-initiated** and **SP-initiated**. You can enable one or both depending on your organization's needs.
### IdP-initiated login (recommended)
Users start their login from your identity provider (Okta, Azure AD, Google Workspace) by clicking an app tile or bookmark. This is the **simplest and most common configuration** - it requires no domain configuration and works automatically once SSO is enabled.
**Best for:**
- Organizations with established IdP workflows
- Multiple SAML apps per domain (Dev, Staging, Prod)
- Simplest user experience
### SP-initiated login
Users start their login at supabase.com by entering their email address, then are redirected to your identity provider. This flow requires configuring email domains to route users to the correct IdP.
**Best for:**
- Users who bookmark supabase.com directly
- Organizations migrating from password authentication
- Supporting domain-based automatic IdP routing
### Need help choosing?
- **Quick decision:** Start with IdP-initiated only (the default). It works for 90% of use cases.
- **Detailed guidance:** See [Choosing the Right Login Flow](/docs/guides/platform/sso/choosing-login-flow) for scenario-based recommendations.
- **Technical details:** Read [Understanding SSO Login Flows](/docs/guides/platform/sso/login-flows) for in-depth explanations.
## Key configuration options
- **Multiple domains** - You can associate one or more email domains with your SSO provider. Users with email addresses matching these domains are eligible to sign in via SSO.
- **Auto-join** - Optionally allow users with a matching domain to be added to your organization automatically when they first sign in, without an invitation.
- **Default role for auto-joined users** - Choose the role (e.g., `Read-only`, `Developer`, `Administrator`, `Owner`) that automatically joined users receive. Refer to [access control](/docs/guides/platform/access-control) for more information about roles.
- **Login flows** - Choose between IdP-initiated (users start from identity provider), SP-initiated (users start at supabase.com), or both. IdP-initiated is recommended for most organizations and requires no domain configuration. See [Choosing the Right Login Flow](/docs/guides/platform/sso/choosing-login-flow) for guidance.
- **Email domains** - Required only if you enable SP-initiated login. You can associate one or more email domains with your SSO provider. Users with matching email addresses can sign in via SSO at supabase.com. Not required for IdP-initiated flow.
- **Auto-join** - Optionally allow users with a matching domain to be added to your organization automatically when they sign in via SSO. Auto-join applies on every login, not just first signup, making it easy to test before enabling.
- **Default role for auto-joined users** - Choose the role (e.g., `Read-only`, `Developer`, `Administrator`, `Owner`) that automatically joined users receive. We recommend using `Developer` as the default (principle of least privilege) and promoting users individually as needed. Refer to [access control](/docs/guides/platform/access-control) for more information about roles.
- **Invitation types** - When inviting users to your organization, you can explicitly choose whether the invitation requires SSO authentication or allows non-SSO login (password/social). This enables mixed authentication organizations with both SSO and non-SSO users.
## How SSO works in Supabase
@@ -47,13 +90,25 @@ When SSO is enabled for an organization:
## Enabling SSO for an organization
- Review the steps above to configure your setup.
- Invite users to the organization and ensure they join with their SSO linked account.
- If a user is already a member of the organization under a non SSO account, they will need to be removed and invited again for them to join under their SSO account.
**Recommended workflow:**
<Admonition type="note">
1. Create or verify at least one non-SSO owner account exists (required for safety)
2. Configure your SSO provider following one of our [provider-specific guides](#supported-providers)
3. Start with auto-join **disabled** to test the configuration
4. Test SSO login with your own account
5. Once confirmed working, enable auto-join if desired
6. Thoroughly test using our [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide
7. Invite users to the organization or let them auto-join on login
**No automatic linking:** Each user account verified using a SSO identity provider will not be automatically linked to existing user accounts in the system. That is, if a user `valid.email@supabase.io` had signed up with a password, and then uses their company SSO login with your project, there will be two `valid.email@supabase.io` user accounts in the system.
<Admonition type="note" label="Account linking">
If a user is already a member of the organization under a non-SSO account, they will need to be removed and invited again with an SSO-required invitation to join under their SSO account. SSO and non-SSO accounts with the same email are treated as separate accounts.
</Admonition>
<Admonition type="note" label="No automatic linking">
Each user account verified using a SSO identity provider will not be automatically linked to existing user accounts in the system. That is, if a user `valid.email@supabase.io` had signed up with a password, and then uses their company SSO login with your project, there will be two `valid.email@supabase.io` user accounts in the system.
Users will need to ensure they are logged in with the correct account when accepting invites or accessing organizations/projects.
@@ -61,7 +116,19 @@ Users will need to ensure they are logged in with the correct account when accep
## Disabling SSO for an organization
If you disable the SSO provider for an organization, **all SSO users will immediately be unable to sign in**. Before disabling SSO, ensure you have at least one non-SSO owner account to prevent being locked out.
If you disable or delete the SSO provider for an organization, **all SSO users will immediately be unable to sign in**.
<Admonition type="caution" label="Safety requirement">
The system requires at least one non-SSO owner account before allowing SSO provider deletion. This prevents complete organization lockout. When you delete an SSO provider, all SSO members are automatically removed from the organization.
Before disabling or deleting SSO:
- Verify a non-SSO owner account exists and can log in
- Communicate to affected users in advance
- Consider whether disabling is better than deleting if the change is temporary
</Admonition>
## Removing an individual SSO user's access
@@ -69,3 +136,25 @@ To revoke access for a specific SSO user without disabling the provider entirely
- Remove or disable the user's account in your identity provider
- Downgrade or remove their permissions for any organizations in Supabase.
## Testing and best practices
Before rolling out SSO to your organization, we strongly recommend thorough testing and following security best practices. Our comprehensive guide covers:
- Step-by-step testing procedures for SSO login, auto-join, and invitations
- Troubleshooting common issues (many of which previously required support intervention)
- Security best practices including certificate monitoring and domain configuration
- Operational guidance for making SSO changes safely
- Pre-launch verification checklist
Visit the [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide for complete details.
## Advanced scenarios
Most organizations use a single SSO provider for all users. However, Supabase supports multiple SSO providers within an organization for advanced use cases such as:
- Separate providers for development, staging, and production environments
- Different providers for different teams or business units
- Gradual migration from one identity provider to another
If you need to configure multiple SSO providers, refer to the [Multiple SSO Providers](/docs/guides/platform/sso/multiple-providers) guide for detailed configuration steps, and contact your Supabase support representative if you need additional guidance.
apps/docs/content/guides/platform/sso/azure.mdx
+24 -6
View File
@@ -110,6 +110,12 @@ We do not permit use of public domains like `gmail.com`, `yahoo.com`.
</Admonition>
<Admonition type="note">
You can configure each SSO provider with different email domains. For multi-environment setups (Dev/Staging/Prod), we recommend using IdP-initiated flow with multiple SAML apps under the same domain rather than domain-based routing. For more details, see the [Multiple SSO Providers guide](/docs/guides/platform/sso/multiple-providers).
</Admonition>
## Step 10: Configure metadata [#dashboard-configure-metadata]
Enter the metadata URL you obtained from [Step 7](#idp-metadata-url) into the Metadata URL field:
@@ -128,7 +134,7 @@ By default this setting is disabled, users logging in via SSO will not be added
![Auto-join disabled](/docs/img/sso-dashboard-configure-autojoin-disabled.png)
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO.
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO. Auto-join applies on **every login**, not just first signup - this makes it safe to test SSO before enabling this feature.
![Auto-join enable](/docs/img/sso-dashboard-configure-autojoin-enabled.png)
@@ -136,18 +142,30 @@ When auto-join is enabled, you can choose the **default role** for new users:
![Auto-join role selection](/docs/img/sso-dashboard-configure-autojoin-enabled-role.png)
Choose a role that fits the level of access you want to grant to new members.
We recommend choosing **Developer** as the default role (principle of least privilege) and promoting users individually as needed.
<Admonition type="note">
Visit [access-control](/docs/guides/platform/access-control) documentation for details about each role.
Read [the Access Control documentation](/docs/guides/platform/access-control) for details about each role.
</Admonition>
## Step 13: Save changes and test single sign-on [#dashboard-configure-save]
## Step 13: Save changes [#dashboard-configure-save]
When you click **Save changes**, your new SSO configuration is applied immediately. From that moment, any user with an email address matching one of your configured domains who visits your organization's sign-in URL will be routed through the SSO flow.
We recommend asking a few users to test signing in via their Azure AD account. They can do this by entering their email address on the [Sign in with SSO](/dashboard/sign-in-sso) page.
## Step 14: Test your SSO configuration
If SSO sign-in doesn't work as expected, contact your Supabase support representative for assistance.
Before rolling out SSO to your organization, we strongly recommend thorough testing. Read [the SSO Testing and Best Practices guide](/docs/guides/platform/sso/testing-best-practices) for:
- Step-by-step testing instructions
- How to verify auto-join works correctly
- Common issues and troubleshooting
- Security best practices
- Pre-launch checklist
<Admonition type="note" label="Testing in Azure sandbox">
If your organization has an Azure sandbox or test tenant, consider testing your SSO configuration there first before applying to production.
</Admonition>
apps/docs/content/guides/platform/sso/choosing-login-flow.mdx
+320
View File
@@ -0,0 +1,320 @@
---
title: 'Choosing the Right SSO Login Flow'
description: 'Quick reference guide to help you choose between IdP-initiated, SP-initiated, or both login flows based on your use case.'
---
Not sure which single sign-on (SSO) login flow to enable? This guide maps common enterprise scenarios to the recommended configuration.
<Admonition type="tip">
Start with identity provider (IdP)-initiated, the default behavior. It requires no domain configuration, and works for most enterprise use cases. You can enable SP-initiated later if needed.
</Admonition>
## Decision flowchart
```
Do users need to start login at supabase.com?
│
├─ No → Use IdP-initiated only (default) ✅
│ - No domain configuration needed
│ - Simplest setup
│ - Users access via IdP dashboard
│
└─ Yes → Do you need multiple SAML apps per domain?
│
├─ Yes → Use IdP-initiated only ✅
│ - Supports Dev/Staging/Prod under same domain
│ - Each environment is a separate IdP tile
│
└─ No → Enable both flows ✅
- SP-initiated for users who bookmark supabase.com
- IdP-initiated still works from IdP dashboard
- Configure email domains
```
## Common scenarios
### Scenario 1: Multiple environments (dev, staging, prod)
**Your situation:**
- You need separate Supabase organizations for Dev, Staging, and Production
- All employees use `company.com` email addresses
- You can't assign different email domains to different environments
**Recommended configuration:** IdP-initiated only ✅
**Why:**
- Create separate SAML apps in your IdP for each environment
- All apps use the same domain (`company.com`)
- Users click "Supabase Dev", "Supabase Staging", or "Supabase Prod" tiles
- No domain conflicts
**How to configure:**
1. In your IdP, create three SAML apps:
- "Supabase Dev" → Points to dev org ACS URL
- "Supabase Staging" → Points to staging org ACS URL
- "Supabase Production" → Points to prod org ACS URL
2. In each Supabase organization:
- Enable SSO
- Leave "Enable SP-initiated login" **OFF**
- Configure metadata from corresponding IdP app
3. Users access each environment via IdP tiles
**Result:** Clean separation of environments with single domain.
---
### Scenario 2: Single production organization
**Your situation:**
- One Supabase organization for your entire company
- All employees use company email domain
- Users are comfortable with IdP dashboard
**Recommended configuration:** IdP-initiated only ✅
**Why:**
- Simplest possible setup
- No domain configuration required
- Users access Supabase with one click from IdP
- Fewer potential failure points
**How to configure:**
1. Enable SSO in your Supabase organization
2. Leave "Enable SP-initiated login" **OFF**
3. Configure identity provider metadata
4. Create Supabase app tile in your IdP
**Result:** One-click SSO login for all users.
---
### Scenario 3: Users bookmark supabase.com
**Your situation:**
- Users frequently bookmark supabase.com directly
- You want to support starting login from Supabase
- Single domain, single organization
**Recommended configuration:** Enable both flows ✅
**Why:**
- Supports users who start at supabase.com (SP-initiated)
- Also supports users who prefer IdP tiles (IdP-initiated)
- Flexible for different user preferences
**How to configure:**
1. Enable SSO in your Supabase organization
2. Toggle "Enable SP-initiated login" **ON**
3. Add your email domain(s) (e.g., `company.com`)
4. Configure identity provider metadata
5. Create Supabase app tile in your IdP (optional but recommended)
**Result:** Users can start login from either Supabase or IdP.
---
### Scenario 4: Migrating from password authentication
**Your situation:**
- Currently using password-based login
- Transitioning to SSO
- Users are used to starting at supabase.com
**Recommended configuration:** Enable both flows ✅
**Why:**
- Familiar login starting point for existing users
- Gradual transition to IdP-based access
- Can promote IdP tiles after users adapt
**How to configure:**
1. Ensure at least one non-SSO owner account exists
2. Enable SSO and toggle "Enable SP-initiated login" **ON**
3. Add email domain(s)
4. Start with auto-join **disabled**
5. Test with small group
6. Enable auto-join once confirmed
7. Communicate new IdP tiles to users
8. Gradually encourage IdP-initiated usage
**Migration path:**
- **Week 1:** Enable both flows, announce SSO availability
- **Week 2-4:** Monitor usage, troubleshoot issues
- **Month 2+:** Promote IdP tiles, consider disabling SP-initiated if usage drops
---
### Scenario 5: Multiple subsidiaries with different domains
**Your situation:**
- Parent company (`parent.com`) and subsidiaries (`sub1.com`, `sub2.com`)
- All use the same Supabase organization
- Each domain maps to same identity provider
**Recommended configuration:** SP-initiated with multiple domains ✅
**Why:**
- Multiple domains supported in SP-initiated configuration
- Automatic routing based on email domain
- Centralized organization management
**How to configure:**
1. Enable SSO in your Supabase organization
2. Toggle "Enable SP-initiated login" **ON**
3. Add all domains: `parent.com`, `sub1.com`, `sub2.com`
4. Configure identity provider to accept all domains
5. Create Supabase app tiles in IdP (IdP-initiated also works)
**Result:** Users with any configured domain can access organization.
---
### Scenario 6: SaaS platform with customer-specific SSO
**Your situation:**
- You're building a SaaS product
- Each customer has their own organization
- Each customer uses their own identity provider
**Recommended configuration:** Per-customer decision (typically IdP-initiated)
**Why:**
- Each customer may have different preferences
- Default to IdP-initiated for simplicity
- Enable SP-initiated only if customer requests it
**How to configure:**
1. For each customer organization:
- Enable SSO with their IdP metadata
- Default: Leave SP-initiated **OFF**
- If customer requests SP-initiated: Toggle **ON** and add their domain
2. Document both options in customer onboarding
3. Let customers choose based on their workflow
**Result:** Flexible, customer-specific SSO configurations.
---
### Scenario 7: Mixed authentication (SSO + non-SSO users)
**Your situation:**
- Some users authenticate via SSO (employees)
- Some users use password/social auth (contractors, external partners)
- Single organization with mixed membership
**Recommended configuration:** Both flows with careful planning ⚠️
**Why:**
- SSO users can use either flow
- Non-SSO users use password/social login
- Separate invitation types for each group
**How to configure:**
1. Enable SSO with both flows (toggle SP-initiated **ON**)
2. Configure employee email domain(s)
3. Use **SSO-required invitations** for employees
4. Use **non-SSO invitations** for contractors
5. Consider disabling auto-join to control membership
<Admonition type="caution" label="Account linking caution">
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:
1. Join via SSO (SSO account)
2. Previously joined via password (non-SSO account)
Communicate clearly which authentication method each user should use.
</Admonition>
**Result:** Mixed authentication with clear separation.
## Configuration quick reference
| Use Case | IdP-initiated | SP-initiated | Domains Required |
| ---------------------------------------- | ------------- | ------------ | ----------------- |
| Multiple environments (Dev/Staging/Prod) | ✅ Only | ❌ Off | No |
| Single production org | ✅ Only | ❌ Off | No |
| Users bookmark supabase.com | ✅ Yes | ✅ Yes | Yes |
| Migrating from passwords | ✅ Yes | ✅ Yes | Yes |
| Multiple email domains | ✅ Yes | ✅ Yes | Yes (all domains) |
| Customer-specific SSO (SaaS) | ✅ Default | Optional | Per customer |
| Mixed authentication | ✅ Yes | ✅ Yes | Yes |
## Testing your configuration
After choosing your login flow, thoroughly test:
1. **IdP-initiated:** Click app tile in IdP → Verify redirect to Supabase
2. **SP-initiated:** Go to supabase.com/sign-in-sso → Enter email → Verify IdP redirect
3. **Auto-join:** Test with new user accounts
4. **Domain restrictions:** Try non-matching domain (should fail for SP-initiated)
See our comprehensive [SSO Testing and Best Practices guide](/docs/guides/platform/sso/testing-best-practices) for detailed testing procedures.
## When to change configuration
You can safely change login flow configuration at any time:
### 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
### Removing SP-initiated
- Toggle "Enable SP-initiated login" OFF
- Domains are preserved (can re-enable later)
- IdP-initiated continues working
- Users who bookmarked supabase.com need to use IdP tiles instead
**No migration required** - Changes take effect immediately.
## Still not sure?
If you're uncertain which configuration to use:
1. Start with IdP-initiated only (simplest, works for most cases)
2. Test with a small group of users
3. Gather feedback on user experience
4. Enable SP-initiated if users request it
5. Monitor usage to see which flow is preferred
<Admonition type="tip" label="Support available">
If you need help choosing the right configuration for your organization, contact Supabase support with details about your use case. We're happy to provide personalized recommendations.
</Admonition>
## Next steps
- **Understand the technical details:** Read [Understanding SSO Login Flows](/docs/guides/platform/sso/login-flows)
- **Configure your provider:** Follow our [provider-specific guides](/docs/guides/platform/sso#supported-providers)
- **Test your setup:** 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)
apps/docs/content/guides/platform/sso/gsuite.mdx
+34 -6
View File
@@ -39,7 +39,13 @@ This is a very important step. Click on _DOWNLOAD METADATA_ and save the file th
![Google Workspace: Web and mobile apps admin console, Add custom SAML, Google Identity Provider details screen](/docs/img/sso-gsuite-step-04.png)
**Important: Make sure the certificate as shown on screen has at least 1 year before it expires. Mark down this date in your calendar so you will be reminded that you need to update the certificate without any downtime for your users.**
**Important: Make sure the certificate as shown on screen has at least 1 year before it expires.**
<Admonition type="caution">
**Certificate expiration:** Set a calendar reminder 30 days before the certificate expiration date. When the certificate is renewed, you'll need to download the new metadata file and update it in your Supabase SSO settings. Expired certificates are a common cause of SSO sign-in failures.
</Admonition>
## Step 5: Add service provider details [#add-service-provider-details]
@@ -102,6 +108,12 @@ We do not permit use of public domains like `gmail.com`, `yahoo.com`.
</Admonition>
<Admonition type="note">
Each SSO provider can be configured with different email domains. For multi-environment setups (Dev/Staging/Prod), we recommend using IdP-initiated flow with multiple SAML apps under the same domain rather than domain-based routing. For more details, see the [Multiple SSO Providers guide](/docs/guides/platform/sso/multiple-providers).
</Admonition>
## Step 10: Configure metadata [#dashboard-configure-metadata]
Upload the metadata file you downloaded in [Step 6](#download-idp-metadata) into the Metadata Upload File field.
@@ -122,11 +134,17 @@ If you did not customize your settings you may save some time by clicking the **
## Step 12: Join organization on signup (optional) [#dashboard-configure-autojoin]
<Admonition type="tip">
**Recommended workflow:** Start with auto-join **disabled** to test your SSO configuration. Once SSO login is working correctly, enable auto-join if desired.
</Admonition>
By default this setting is disabled, users logging in via SSO will not be added to your organization automatically.
![Auto-join disabled](/docs/img/sso-dashboard-configure-autojoin-disabled.png)
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO.
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO. Auto-join applies on **every login**, not just first signup - this makes it safe to test SSO before enabling this feature.
![Auto-join enable](/docs/img/sso-dashboard-configure-autojoin-enabled.png)
@@ -134,7 +152,7 @@ When auto-join is enabled, you can choose the **default role** for new users:
![Auto-join role selection](/docs/img/sso-dashboard-configure-autojoin-enabled-role.png)
Choose a role that fits the level of access you want to grant to new members.
We recommend choosing **Developer** as the default role (principle of least privilege) and promoting users individually as needed.
<Admonition type="note">
@@ -142,10 +160,20 @@ Visit [access-control](/docs/guides/platform/access-control) documentation for d
</Admonition>
## Step 13: Save changes and test single sign-on [#dashboard-configure-save]
## Step 13: Save changes [#dashboard-configure-save]
When you click **Save changes**, your new SSO configuration is applied immediately. From that moment, any user with an email address matching one of your configured domains who visits your organization's sign-in URL will be routed through the SSO flow.
We recommend asking a few users to test signing in via their Google Workspace account. They can do this by entering their email address on the [Sign in with SSO](/dashboard/sign-in-sso) page.
<Admonition type="tip">
If SSO sign-in doesn't work as expected, contact your Supabase support representative for assistance.
**Next step: Test your SSO configuration**
Before rolling out SSO to your organization, we strongly recommend thorough testing. Visit our [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide for:
- Step-by-step testing instructions
- How to verify auto-join works correctly
- Common issues and troubleshooting
- Security best practices
- Pre-launch checklist
</Admonition>
apps/docs/content/guides/platform/sso/login-flows.mdx
+267
View File
@@ -0,0 +1,267 @@
---
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
apps/docs/content/guides/platform/sso/multiple-providers.mdx
+546
View File
@@ -0,0 +1,546 @@
---
title: 'Multiple SSO Providers'
description: 'Configure multiple SSO providers for different environments, teams, or use cases'
---
Many enterprises need multiple single sign-on (SSO) providers configured within Supabase to support different environments, teams, or organizational structures. This guide explains when and how to set up multiple providers effectively.
## Why multiple SSO providers?
Common scenarios requiring multiple SSO providers include:
- **Multiple environments**: Separate Dev, Staging, and Production organizations
- **Team separation**: Different business units or departments
- **Migration**: Transitioning from one identity provider to another
- **Acquisitions**: Integrating subsidiaries with different identity systems
- **Testing**: Isolated test environments alongside production
## Key concept: IDP-initiated enables unlimited providers per domain
The traditional challenge with multiple SAML apps is domain conflicts. With SP-initiated flow only, each SAML app requires a unique email domain. Since all your employees use the same domain (e.g., `company.com`), this creates a problem.
**Solution:** Use identity provider (IdP)-initiated flow, which doesn't require domain configuration. You can create unlimited SAML apps under the same domain.
<Admonition type="tip" label="Recommended pattern">
Configure each environment as IdP-initiated only (no domains). Users access each environment through different app tiles in your identity provider.
For technical details, see [the Understanding SSO Login Flows guide](/docs/guides/platform/sso/login-flows#multiple-saml-apps-per-domain).
</Admonition>
## Use case 1: Multiple environments (dev/staging/prod)
This is the most common enterprise pattern and the primary use case for IDP-initiated flow.
### The challenge
You have three Supabase organizations:
- Development (`dev-org`)
- Staging (`staging-org`)
- Production (`prod-org`)
All employees use `company.com` email addresses. You need separate SSO configurations for each environment.
### The solution
Create three separate SAML apps in your identity provider, each pointing to a different Supabase organization.
#### In your identity provider (Okta, Azure AD, Google Workspace)
1. **Create "Supabase Dev" SAML app**
- Configure with Dev organization's ACS URL
- Assign developers and testers
- Deploy app tile labeled "Supabase Dev"
2. **Create "Supabase Staging" SAML app**
- Configure with Staging organization's ACS URL
- Assign QA team and release managers
- Deploy app tile labeled "Supabase Staging"
3. **Create "Supabase Production" SAML app**
- Configure with Production organization's ACS URL
- Assign production users only
- Deploy app tile labeled "Supabase Production"
#### In each Supabase organization
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) section of the dashboard
2. Enable **Single Sign-On**
3. Leave **Enable SP-initiated login** "OFF", this is critical
4. Configure metadata from the corresponding IDP app
5. Set up attribute mappings
6. Configure auto-join if desired
### Result
- Users click the appropriate app tile for the environment they need
- No domain conflicts (all apps use `company.com`)
- Clean isolation between environments
- Each environment can have different user assignments and roles
### Configuration example
Here's how the three configurations differ:
| Environment | Organization | IDP App Name | ACS URL |
| ----------- | ------------ | ------------------ | ------------------------------------ |
| Dev | `dev` | "Supabase Dev" | `https://...dev-org.../saml/acs` |
| Staging | `staging` | "Supabase Staging" | `https://...staging-org.../saml/acs` |
| Production | `prod` | "Supabase Prod" | `https://...prod-org.../saml/acs` |
#### Each organization
- SP-initiated: **OFF** (no domains configured)
- IDP-initiated: **ON** (automatic, no configuration needed)
- Auto-join: Your preference (typically enabled for dev, disabled for prod)
## Use case 2: Different teams or business units
Some organizations need to isolate teams within separate Supabase organizations.
### Example scenario
- Engineering team uses `engineering-org`
- Data team uses `data-org`
- Both teams have `company.com` emails
### Configuration approach
#### Option A: IDP-initiated with different app tiles
Create separate SAML apps in your IDP:
- "Supabase Engineering" → Points to `engineering-org`
- "Supabase Data" → Points to `data-org`
Assign appropriate users to each app. Users only see the tiles they're assigned to.
#### Option B: Both IDP and SP-initiated with role-based routing
Configure both organizations with SP-initiated enabled using the same domain:
- Both organizations add `company.com` as a domain
- Users can log in via SP-initiated at supabase.com
- System routes based on org membership (first match wins)
- Also provide IDP tiles for explicit routing
<Admonition type="caution" label="SP-initiated routing with multiple providers">
When multiple organizations use SP-initiated with the same domain, the first provider where the user is a member will be used. This can cause confusion. **IDP-initiated is recommended** for clarity.
</Admonition>
## Use case 3: Migration from one IDP to another
When migrating from one identity provider to another, multiple providers help ensure a smooth transition.
### Migration workflow
#### Phase 1: Dual configuration
1. Configure new IDP as additional SSO provider
2. Keep existing IDP active
3. Test new IDP with small group
4. Both providers operational simultaneously
#### Phase 2: Gradual rollout
1. Migrate users in batches to new IDP
2. Update app tile assignments
3. Monitor for issues
4. Keep old IDP as fallback
#### Phase 3: Cutover
1. Move all users to new IDP
2. Verify no users depend on old IDP
3. Disable (don't delete) old IDP provider
4. Monitor for any issues
#### Phase 4: Cleanup
1. After verification period (1-2 weeks)
2. Delete old IDP provider
3. Update documentation
<Admonition type="caution">
Always maintain at least one non-SSO owner account during migrations to ensure you never lose access to the organization.
</Admonition>
## Use case 4: Acquisitions and subsidiaries
Organizations with multiple email domains need provider configurations for each domain.
### Example scenario
- Parent company: `parent.com`
- Subsidiary 1: `subsidiary1.com`
- Subsidiary 2: `subsidiary2.com`
All authenticate through the same central IDP but use different email domains.
### Configuration approach
#### Option A: Single provider with multiple domains (SP-initiated)
1. Enable SSO with SP-initiated flow
2. Add all domains: `parent.com`, `subsidiary1.com`, `subsidiary2.com`
3. Configure single IDP metadata
4. Users with any matching domain can log in via supabase.com
#### Option B: Separate providers per subsidiary (IDP-initiated)
1. Create separate SAML apps for each entity
2. Configure as IDP-initiated only
3. Assign users based on their subsidiary
4. More isolation, clearer organization boundaries
## Step-by-step setup guide
### For IDP-initiated multi-environment pattern
This is the recommended pattern for most enterprises.
#### Step 1: Plan your environments
Document:
- Organization names and slugs
- Environment purposes (dev, staging, prod)
- Which users need access to which environments
- Default roles for each environment
#### Step 2: Create SAML apps in your IDP
For each environment, follow your provider-specific guide to create a SAML app:
- [Okta setup guide](/docs/guides/platform/sso/okta)
- [Azure AD setup guide](/docs/guides/platform/sso/azure)
- [Google Workspace setup guide](/docs/guides/platform/sso/gsuite)
#### Naming convention example
- "Supabase - Production"
- "Supabase - Staging"
- "Supabase - Development"
Use consistent naming to help users identify the right environment.
#### Step 3: Configure each Supabase organization
For **each** organization:
1. Navigate to [the **SSO** settings](/dashboard/org/_/sso) section of the dashboard
2. Enable **Single Sign-On**
3. Verify **Enable SP-initiated login** is "OFF"
4. Upload or paste metadata from the corresponding IDP app
5. Configure attribute mappings:
- Email (required): Map to `email`
- Name (optional): Map to `name` or `displayName`
6. Configure auto-join settings:
- Dev: Usually enabled with "Developer" role
- Staging: Usually enabled with "Developer" role
- Prod: Usually disabled (explicit invitations only)
7. Save configuration
#### Step 4: Test each environment separately
For each environment:
1. Open your IDP dashboard (Okta, Azure, Google)
2. Click the corresponding app tile
3. Verify redirect to correct Supabase organization
4. Check that user information is populated correctly
5. Verify auto-join behavior (if enabled)
See [the SSO Testing and Best Practices guide](/docs/guides/platform/sso/testing-best-practices) for comprehensive testing procedures.
#### Step 5: Assign users in your IDP
Configure app assignments in your IDP:
- **Production**: Only production users (restrictive)
- **Staging**: QA team, release managers, senior engineers
- **Development**: All engineers and testers (permissive)
Users only see app tiles they're assigned to.
#### Step 6: Document and communicate
Create documentation for your team:
- Which app tile corresponds to which environment
- Access request process for each environment
- Naming conventions and organization structure
- Emergency access procedures (non-SSO owner account)
## User access management
### IDP app assignment strategies
#### Per-environment access control
Control who can access each environment by managing app assignments in your IDP:
```
Engineering Team:
├─ Supabase Dev (assigned) ✅
├─ Supabase Staging (assigned) ✅
└─ Supabase Prod (assigned) ✅
QA Team:
├─ Supabase Dev (assigned) ✅
├─ Supabase Staging (assigned) ✅
└─ Supabase Prod (NOT assigned) ❌
Contractors:
├─ Supabase Dev (assigned) ✅
├─ Supabase Staging (NOT assigned) ❌
└─ Supabase Prod (NOT assigned) ❌
```
### Role assignment patterns
#### Option 1: Different default roles per environment
- Dev: Auto-join with "Administrator" role (developers need full control)
- Staging: Auto-join with "Developer" role
- Prod: No auto-join, explicit invitations with "Read-only" or "Developer"
#### Option 2: Consistent roles, manual promotion
- All environments: Auto-join with "Developer" role
- Promote to "Administrator" or "Owner" manually as needed
- Provides consistent baseline, explicit elevation
#### Option 3: No auto-join, explicit control
- All environments: Auto-join disabled
- Send explicit invitations with appropriate roles
- Maximum control, more management overhead
Choose based on your organization's security posture and operational preferences.
## Best practices
### Naming conventions
#### IDP app names
Use consistent, descriptive names that clearly indicate the environment:
- ✅ "Supabase - Production"
- ✅ "Supabase Prod"
- ❌ "Supabase" (ambiguous)
- ❌ "SUPA_PROD" (unclear abbreviation)
#### Supabase organization names
Match your IDP app names when possible:
- IDP app: "Supabase - Production" → Org: `acme-production`
- IDP app: "Supabase - Staging" → Org: `acme-staging`
- IDP app: "Supabase - Dev" → Org: `acme-development`
### Configuration synchronization
Keep critical settings synchronized across environments:
- **Attribute mappings**: Should be identical across all providers
- **Certificate settings**: Coordinate renewals across all environments
- **Safety accounts**: Each org needs a non-SSO owner account
#### Configuration drift checklist
- [ ] Attribute mappings match across environments
- [ ] Certificate expiration dates documented for all providers
- [ ] Non-SSO owner accounts exist in all organizations
- [ ] Auto-join settings are intentional (not accidental)
- [ ] Default roles appropriate for each environment
### Testing in lower environments first
Always test SSO changes in non-production environments:
1. **Make change in Dev environment**
2. **Test thoroughly** (see [testing guide](/docs/guides/platform/sso/testing-best-practices))
3. **Deploy to Staging** and verify
4. **Monitor for issues** (1-2 days)
5. **Deploy to Production** during low-usage period
6. **Monitor closely** after production deployment
### Security considerations
#### Environment isolation
- Never reuse metadata between environments (security risk)
- Each environment should have unique ACS URLs
- Verify IDP app assignments are correct (don't give prod access accidentally)
#### Access reviews
- Quarterly review of who has access to production
- Verify IDP app assignments are up to date
- Remove access for users who have changed roles
- Audit auto-join configurations (still appropriate?)
#### Break-glass access
Each organization must have at least one non-SSO owner account:
- Create dedicated "break-glass" accounts
- Store credentials in secure password manager
- Test these accounts regularly (quarterly)
- Document emergency access procedures
## Troubleshooting
### Users accessing the wrong environment
#### Symptom
User clicks "Supabase Prod" tile but sees the dev environment.
#### Causes
- Metadata configured incorrectly (swapped between environments)
- ACS URL points to wrong organization
- User has bookmarked the wrong organization
#### Solution
1. Verify ACS URL in IDP app configuration
2. Compare metadata in Supabase SSO settings
3. Check that organization slug matches expected environment
4. Have user clear browser cookies and try again
5. Verify user is clicking correct app tile
### 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
1. Compare SSO configurations side-by-side
2. Check attribute mappings are identical
3. Verify certificate expiration dates
4. Test with same user account across all environments
5. Review IDP audit logs for authentication failures
### Users don't see expected app tiles
#### Symptom
User cannot find "Supabase Staging" tile in IDP dashboard.
#### Causes
- User not assigned to the app in IDP
- App not deployed/published in IDP
- User looking in wrong place (different IDP portal)
#### Solution
1. Verify app assignment in IDP admin console
2. Check app is published/active
3. Confirm user has logged out and back into IDP
4. Verify user is checking correct IDP portal (some organizations have multiple)
### Auto-join adding users to wrong organization
#### Symptom
User joins dev environment when they should join production.
#### Cause
User clicked wrong app tile, auto-join is enabled.
#### Prevention
- Disable auto-join in production (explicit invitations only)
- Use clear app tile naming
- Document which tile corresponds to which environment
- Consider using different IDP groups for different environments
#### Remediation
1. Remove user from incorrect organization
2. Send explicit invitation to correct organization
3. Educate user on correct app tile to use
4. Consider disabling auto-join to prevent recurrence
### Multiple organizations with same domain (SP-initiated confusion)
#### 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
## Migration from single to multiple providers
If you currently have a single SSO provider and need to add more:
### Phase 1: Planning
1. Decide which pattern to use (environments, teams, etc.)
2. Document new organization structure
3. Identify users for each environment
4. Plan user communication strategy
### Phase 2: Create new organizations
1. Create additional Supabase organizations
2. Configure projects within each organization
3. Migrate data if needed (see [project transfer](/docs/guides/platform/project-transfer))
### Phase 3: Configure SSO providers
1. Create additional SAML apps in your IDP
2. Configure SSO in each new organization
3. Start with auto-join disabled
4. Test with small group
### Phase 4: Migrate users
1. Communicate changes to users
2. Assign users to appropriate IDP apps
3. Test that users can access correct environments
4. Enable auto-join if desired
### Phase 5: Decommission old configuration (if applicable)
1. Migrate all users to new structure
2. Verify no one depends on old configuration
3. Disable old SSO provider
4. Monitor for issues
5. Delete after verification period
## Next steps
- **Configure your IDP:** Follow your [provider-specific guide](/docs/guides/platform/sso#supported-providers)
- **Test thoroughly:** Review [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices)
- **Understand login flows:** Read [Understanding SSO Login Flows](/docs/guides/platform/sso/login-flows)
- **Choose the right flow:** See [Choosing the Right Login Flow](/docs/guides/platform/sso/choosing-login-flow)
apps/docs/content/guides/platform/sso/okta.mdx
+33 -5
View File
@@ -94,6 +94,12 @@ We do not permit use of public domains like `gmail.com`, `yahoo.com`.
</Admonition>
<Admonition type="note">
Each SSO provider can be configured with different email domains. For multi-environment setups (Dev/Staging/Prod), we recommend using IdP-initiated flow with multiple SAML apps under the same domain rather than domain-based routing. For more details, see the [Multiple SSO Providers guide](/docs/guides/platform/sso/multiple-providers).
</Admonition>
## Step 9: Configure metadata [#dashboard-configure-metadata]
Enter the metadata URL you obtained from [Step 6](#idp-metadata-url) into the Metadata URL field:
@@ -114,11 +120,17 @@ If you did not customize your settings you may save some time by clicking the **
## Step 11: Join organization on signup (optional) [#dashboard-configure-autojoin]
<Admonition type="tip">
**Recommended workflow:** Start with auto-join **disabled** to test your SSO configuration. Once SSO login is working correctly, enable auto-join if desired.
</Admonition>
By default this setting is disabled, users logging in via SSO will not be added to your organization automatically.
![Auto-join disabled](/docs/img/sso-dashboard-configure-autojoin-disabled.png)
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO.
Toggle this on if you want SSO-authenticated users to be **automatically added to your organization** when they log in via SSO. Auto-join applies on **every login**, not just first signup - this makes it safe to test SSO before enabling this feature.
![Auto-join enable](/docs/img/sso-dashboard-configure-autojoin-enabled.png)
@@ -126,7 +138,7 @@ When auto-join is enabled, you can choose the **default role** for new users:
![Auto-join role selection](/docs/img/sso-dashboard-configure-autojoin-enabled-role.png)
Choose a role that fits the level of access you want to grant to new members.
We recommend choosing **Developer** as the default role (principle of least privilege) and promoting users individually as needed.
<Admonition type="note">
@@ -134,10 +146,26 @@ Visit [access-control](/docs/guides/platform/access-control) documentation for d
</Admonition>
## Step 12: Save changes and test single sign-on [#dashboard-configure-save]
## Step 12: Save changes [#dashboard-configure-save]
When you click **Save changes**, your new SSO configuration is applied immediately. From that moment, any user with an email address matching one of your configured domains who visits your organization's sign-in URL will be routed through the SSO flow.
We recommend asking a few users to test signing in via their Okta account. They can do this by entering their email address on the [Sign in with SSO](/dashboard/sign-in-sso) page.
<Admonition type="tip">
If SSO sign-in doesn't work as expected, contact your Supabase support representative for assistance.
**Next step: Test your SSO configuration**
Before rolling out SSO to your organization, we strongly recommend thorough testing. Visit our [SSO Testing and Best Practices](/docs/guides/platform/sso/testing-best-practices) guide for:
- Step-by-step testing instructions
- How to verify auto-join works correctly
- Common issues and troubleshooting
- Security best practices
- Pre-launch checklist
</Admonition>
<Admonition type="note">
**Testing in Okta sandbox:** If your organization has an Okta sandbox environment, consider testing your SSO configuration there first before applying to production.
</Admonition>
apps/docs/content/guides/platform/sso/testing-best-practices.mdx
+844
View File
@@ -0,0 +1,844 @@
---
title: 'SSO Testing and Best Practices'
description: 'Comprehensive guide to testing SSO configuration and best practices for secure, reliable single sign-on.'
---
After configuring your SSO provider, thorough testing is essential before rolling out to your organization. This guide covers testing procedures, troubleshooting common issues, and best practices for maintaining a secure SSO setup.
## Pre-configuration checklist
Before you begin testing, verify:
- [ ] Organization has Team or Enterprise plan
- [ ] Login flow type decided (IdP-initiated, SP-initiated, or both) - see [Choosing a Login Flow](/docs/guides/platform/sso/choosing-login-flow)
- [ ] Email domains identified (only required if using SP-initiated)
- [ ] Auto-join settings and default role are decided
- [ ] **At least one non-SSO owner account exists** (critical safety requirement)
- [ ] Certificate expiration dates are documented (especially for Google Workspace)
## Testing login flows
Before testing auto-join and other features, verify which login flows work for your SSO configuration. See [Understanding SSO Login Flows](/docs/guides/platform/sso/login-flows) for technical details.
### Testing IdP-initiated login
IdP-initiated login is always available and doesn't require domain configuration. This should be your primary test.
**Test procedure:**
1. **Access from identity provider:**
- Open your IdP dashboard (Okta, Azure AD, Google Workspace)
- Locate your Supabase app tile or bookmark
- Click the app tile
2. **Verify authentication:**
- If already authenticated with IdP: Immediate redirect to Supabase
- If not authenticated: Complete IdP login flow, then redirect
- Check you're logged into the correct organization
- Verify user profile information is populated correctly
3. **Confirm success:**
- No error messages appear
- Organization dashboard loads properly
- User attributes (name, email) mapped correctly
**Expected results:**
- ✅ Direct login from IdP with no intermediate steps
- ✅ Works regardless of domain configuration
- ✅ User information properly mapped from IdP
### Testing SP-initiated login
SP-initiated login requires domain configuration. Only test this if you've enabled SP-initiated flow.
<Admonition type="note">
If you haven't configured domains or have "Enable SP-initiated login" disabled, skip this test. SP-initiated will not work without domain configuration.
</Admonition>
**Prerequisites:**
- "Enable SP-initiated login" toggle is **ON**
- At least one email domain configured
**Test procedure:**
1. **Start at Supabase:**
- Visit [Sign in with SSO](/dashboard/sign-in-sso)
- Or click "Sign in with SSO" from main sign-in page
2. **Enter email:**
- Use email with matching configured domain
- Click "Continue"
3. **Verify redirect chain:**
- Should redirect to your identity provider
- Complete authentication if needed
- Should redirect back to Supabase
- Check you're in correct organization
4. **Test domain matching:**
- Try email with non-matching domain
- Should receive error: "No SSO provider found"
- Confirms domain-based routing works
**Expected results:**
- ✅ Users with matching domains redirected to IdP
- ✅ Non-matching domains show clear error message
- ✅ Successful authentication redirects back to Supabase
### Testing without domains (IdP-initiated only)
This is a critical test for domainless providers, which enable multiple SAML apps per domain.
**Test scenario:**
You've configured SSO with:
- "Enable SP-initiated login" **OFF** (or no domains configured)
- IdP metadata configured
- Attribute mappings configured
**Test procedure:**
1. **Verify SP-initiated is unavailable:**
- Visit [Sign in with SSO](/dashboard/sign-in-sso)
- Enter your email address
- Expected: Error message "No SSO provider found"
- This is correct behavior (no domains = no SP-initiated)
2. **Verify IdP-initiated works:**
- Open IdP dashboard
- Click Supabase app tile
- Should successfully log in
- Verify correct organization access
3. **Confirm multi-environment pattern works (if applicable):**
- If you have multiple environments (Dev/Staging/Prod)
- Each should have separate app tile in IdP
- Click each tile individually
- Verify each routes to correct organization
**Expected results:**
- ✅ IdP-initiated login works perfectly
- ❌ SP-initiated login unavailable (expected)
- ✅ Multiple environments accessible via different tiles
- ✅ No domain conflicts between environments
<Admonition type="tip">
**Multiple environments:** If you're setting up Dev/Staging/Prod, this domainless pattern is recommended. See [Multiple SSO Providers](/docs/guides/platform/sso/multiple-providers) for detailed configuration guidance.
</Admonition>
### Login flow verification checklist
- [ ] IdP-initiated login works from IdP dashboard
- [ ] SP-initiated login works (if domains configured)
- [ ] SP-initiated properly blocked if no domains configured
- [ ] Domain matching works correctly for SP-initiated
- [ ] Non-matching domains show appropriate errors
- [ ] Multiple environments route correctly (if using multiple providers)
- [ ] Both flows work simultaneously (if both enabled)
## Testing SSO login flow
### Basic login test
1. **Navigate to the SSO sign-in page**:
- Visit [Sign in with SSO](/dashboard/sign-in-sso)
- Or click "Sign in with SSO" from the main Supabase sign-in page
2. **Enter your email address**:
- Use an email with a domain configured in your SSO settings
- Click "Continue"
3. **Verify redirect to identity provider**:
- You should be redirected to your identity provider (Okta, Azure AD, Google Workspace)
- If already signed in to your IdP, you may be automatically redirected back
- If not signed in, complete the IdP login flow
4. **Confirm successful sign-in**:
- You should be redirected back to Supabase dashboard
- Your profile should show your SSO identity
- Check that your user information is populated correctly
### Multi-user testing
Test with 2-3 additional users to verify:
- Users with matching email domains can sign in via SSO
- User attributes (name, email) are mapped correctly
- Users receive appropriate access to organization (if using auto-join)
- Users without matching domains cannot use SSO for this organization
## Testing auto-join
<Admonition type="caution">
**Recent improvement:** Auto-join now applies on EVERY login, not just first signup. This resolves a common issue where org owners would test with auto-join disabled, enable it, then log in again expecting to auto-join.
</Admonition>
### Recommended testing workflow
1. **Start with auto-join disabled**:
- Navigate to [SSO settings](/dashboard/org/_/sso)
- Ensure "Join organization on signup" is **disabled**
- Configure your SSO provider
- Test basic SSO login (see above)
2. **Enable auto-join after successful test**:
- Return to [SSO settings](/dashboard/org/_/sso)
- Toggle "Join organization on signup" to **enabled**
- Select default role (recommended: **Developer**)
- Click "Save changes"
3. **Test auto-join with your account**:
- **Log out completely** from Supabase
- Sign in again via SSO
- Verify you were automatically added to the organization
- Check you received the correct default role
4. **Test with additional users**:
- Have colleagues with matching email domains sign in via SSO
- They should automatically join the organization
- Verify they received the correct default role
- Check organization members list at `/dashboard/org/_/team`
5. **Test domain restrictions (if using SP-initiated)**:
- Try signing in with an email from a non-configured domain
- User should be able to sign in but will NOT see the organization
- This confirms domain-based access control is working
- Note: With IdP-initiated only, domain matching doesn't apply
6. **Test idempotency (prevents duplicate memberships)**:
- Log in again with an account that's already a member
- Verify no error occurs
- Check members list - should be no duplicate entry
- Confirm role hasn't changed unexpectedly
- Expected: Auto-join gracefully handles existing members
7. **Test with domainless (IdP-initiated only) configuration**:
<Admonition type="note">
This test is critical if you're using multiple environments under the same domain. See [Multiple SSO Providers](/docs/guides/platform/sso/multiple-providers) for details.
</Admonition>
- If you configured SSO without domains (IdP-initiated only):
- Enable auto-join
- New user accesses via IdP app tile
- Verify auto-join works without domain check
- User automatically added to organization
- Correct role assigned
- Expected: Auto-join works for IdP-initiated regardless of email domain
8. **Test auto-join re-enablement**:
- Disable auto-join
- Have new user sign in via SSO
- Verify they are NOT added to organization
- Re-enable auto-join
- Same user logs out and logs in again
- Verify they ARE now added to organization
- Expected: Existing SSO users auto-join when feature is enabled
### Auto-join verification checklist
- [ ] Auto-join works when enabled
- [ ] Users receive correct default role
- [ ] Non-matching domains are excluded (if using SP-initiated with domains)
- [ ] Existing users auto-join on their next login (not just new signups)
- [ ] Auto-join can be disabled and re-enabled as needed
- [ ] Auto-join is idempotent (no duplicate memberships)
- [ ] Auto-join works with IdP-initiated only (no domains)
- [ ] Auto-join works with both IdP and SP-initiated flows
## Testing invitations
<Admonition type="caution">
**Recent improvement:** You can now explicitly choose whether an invitation requires SSO or non-SSO authentication. Previously, this was inherited from the inviter's account type, which caused confusion.
</Admonition>
### Creating and testing invitations
1. **Create SSO-required invitation**:
- Navigate to [organization team settings](/dashboard/org/_/team)
- Click "Invite" to create a new invitation
- Select **"Require SSO"** option
- Enter recipient email and select role
- Send invitation
- Recipient must log in via SSO to accept
2. **Create non-SSO invitation**:
- Create a new invitation
- Select **"Non-SSO"** option
- Send invitation
- Recipient can use password or social login to accept
3. **Test SSO mismatch scenario**:
- Create an SSO-required invitation
- Have recipient try to accept while logged in with a non-SSO account
- Error should display: "Invite token SSO provider does not match the one you are logged in with"
- Recipient should log out and sign in via SSO
- Can then successfully accept the invitation
### Common invitation scenarios
- **All-SSO organization**: Always select "Require SSO" for invitations
- **Mixed organization**: Choose based on recipient's authentication method
- **Transitioning to SSO**: Start with non-SSO users, gradually add SSO users, maintain non-SSO owner before removing old authentication methods
### Invitation verification checklist
- [ ] SSO-required invitations work correctly
- [ ] Non-SSO invitations work correctly
- [ ] SSO mismatch error message is clear
- [ ] Mixed authentication organization functions properly
- [ ] Invitations can be resent if needed
<Admonition type="note">
If you're configuring multiple SSO providers for different environments (dev/staging/prod), the testing steps outlined here apply to each provider individually. For advanced multi-provider configuration strategies, see the [Multiple SSO Providers guide](/docs/guides/platform/sso/multiple-providers).
</Admonition>
## Testing SSO account restrictions
SSO accounts have specific restrictions to prevent accidental organization lockouts.
<Admonition type="caution">
**Safety mechanism:** SSO accounts cannot delete SSO providers. This prevents scenarios where an SSO user could accidentally lock out the entire organization by deleting the SSO provider they use to authenticate.
</Admonition>
### Testing SSO account deletion restrictions
1. **Log in with SSO account:**
- Authenticate via SSO (IdP or SP-initiated)
- Navigate to [SSO settings](/dashboard/org/_/sso)
- Verify you are an organization owner
2. **Attempt to delete SSO provider:**
- Try to delete the SSO provider
- **Expected:** Error message preventing deletion
- Error: "Only a non-SSO account may delete an SSO Provider"
- Deletion should be blocked
3. **Verify other SSO operations work:**
- SSO accounts CAN read SSO configuration
- SSO accounts CAN update SSO settings
- SSO accounts CAN disable (but not delete) SSO provider
- Only deletion is restricted
**Expected results:**
- ❌ SSO accounts cannot delete SSO providers
- ✅ Clear error message explains the restriction
- ✅ Other SSO management operations still work
### Testing with non-SSO owner account
1. **Log in with non-SSO owner:**
- Use password or social auth account
- Must be organization owner
- Navigate to [SSO settings](/dashboard/org/_/sso)
2. **Verify deletion capability:**
- Non-SSO owners CAN delete SSO providers
- Deletion subject to additional safety checks (see next section)
- System allows proceeding to deletion flow
**Expected results:**
- ✅ Non-SSO owners CAN access deletion functionality
- ✅ Safety checks still apply (non-SSO account requirement)
### SSO account restrictions checklist
- [ ] SSO accounts cannot delete SSO providers
- [ ] SSO accounts CAN update SSO settings
- [ ] SSO accounts CAN disable SSO providers
- [ ] Non-SSO owners CAN delete SSO providers
- [ ] Error messages clearly explain the restriction
- [ ] Restriction applies to all SSO accounts (not just certain roles)
## Common issues and troubleshooting
Based on customer pain points that previously required support intervention:
### Critical issues
#### "Enabled auto-join but users aren't automatically joining"
**Common workflow that causes this:**
1. Org owner tests SSO with auto-join disabled
2. Enables auto-join after testing
3. Logs in again expecting to auto-join but nothing happens
**Solution:**
- Auto-join now applies on **every login**, not just first signup
- To test: Enable auto-join, log out completely, log back in via SSO
- If still not working, verify domain configuration matches user email exactly
#### "Can't invite users with the right authentication type"
**Previous limitation:**
- Invitation type was inherited from inviter's account type
- Non-SSO owners couldn't send SSO invitations
- SSO owners couldn't send non-SSO invitations
**Solution:**
- When creating invitations, explicitly choose "Require SSO" or "Non-SSO"
- Mixed organizations are now fully supported
- Both SSO and non-SSO users can coexist in the same organization
#### "Invitation acceptance shows 'SSO provider mismatch' error"
**Cause:** User is logged in with wrong authentication method for the invitation
**Solution:**
1. Check if invitation requires SSO or non-SSO login
2. Log out completely
3. Sign in with the correct method (SSO or password/social)
4. Accept the invitation
5. Contact the person who sent the invitation if unsure about the type
#### "Deleted the SSO provider and now members can't log in"
**Recent safety improvements:**
- System now automatically removes all SSO members before deletion
- Must have at least one non-SSO owner before deletion is allowed
**Best practice:**
- Add a non-SSO owner account **before** deleting SSO provider
- Communicate to affected users before deletion
- Consider disabling rather than deleting if change is temporary
## Testing safe provider deletion
<Admonition type="danger">
**Critical safety checks:** Deleting an SSO provider automatically removes ALL SSO members from the organization. The system enforces multiple safety checks to prevent complete organization lockout.
**Only test deletion in non-production environments or test organizations.** Do not test this in your actual production organization unless you fully understand the consequences.
</Admonition>
### Understanding deletion behavior
When an SSO provider is deleted:
1. System verifies at least one non-SSO owner account exists
2. **All SSO members are automatically removed** from the organization
3. SSO provider configuration is deleted
4. Organization continues operating with remaining non-SSO members
This behavior prevents "orphaned" SSO accounts that can no longer authenticate.
### Test 1: Deletion without non-SSO accounts (should fail)
**Setup:**
- Organization with only SSO accounts
- All owners authenticate via SSO
- No password or social auth owners exist
**Test procedure:**
1. **Verify current state:**
- Check [team settings](/dashboard/org/_/team)
- Confirm all owners are SSO accounts
- No non-SSO owner exists
2. **Attempt deletion:**
- Navigate to [SSO settings](/dashboard/org/_/sso)
- Try to delete SSO provider
- **Expected:** Error preventing deletion
- Error message: "At least one non-SSO account is required to maintain organization access"
3. **Verify organization state:**
- SSO provider still exists
- All SSO members still have access
- No partial deletion occurred
**Expected result:** ❌ Deletion blocked with clear error message
### Test 2: Add non-SSO owner and retry deletion (should succeed)
<Admonition type="caution">
**Warning:** This test WILL remove all SSO members. Only perform in test organizations.
</Admonition>
**Setup:**
1. **Add non-SSO owner:**
- Create or invite a non-SSO user (password or social login)
- Promote to owner role
- **Critical:** Verify non-SSO owner can log in BEFORE deletion
- Store credentials securely
2. **Document SSO members:**
- Note current SSO member count
- Document SSO member email addresses (for verification)
**Test procedure:**
1. **Attempt deletion as non-SSO owner:**
- Log in with non-SSO owner account
- Navigate to [SSO settings](/dashboard/org/_/sso)
- Delete SSO provider
- Confirm deletion
2. **Verify deletion results:**
- All SSO members removed from organization
- Check [team settings](/dashboard/org/_/team)
- Only non-SSO members should remain
- SSO configuration completely removed
3. **Verify non-SSO access:**
- Non-SSO owner retains full access
- Organization remains functional
- Can invite new members (non-SSO invitations)
**Expected result:** ✅ Deletion succeeds, SSO members removed, non-SSO access preserved
### Test 3: Member removal during deletion
**Test in isolated environment with test accounts.**
**Setup:**
1. Create test organization
2. Enable SSO
3. Add multiple SSO members (3-5 test users)
4. Add at least one non-SSO owner
5. Document member list before deletion
**Test procedure:**
1. **Track members before deletion:**
- Note SSO member count (e.g., 5 SSO members)
- Note SSO member email addresses
- Document their roles
2. **Delete SSO provider:**
- Log in as non-SSO owner
- Delete SSO provider
- System may show member count being removed
3. **Verify member removal:**
- Check organization members list
- All SSO members should be gone
- Only non-SSO members remain
- Previous SSO users cannot access org
**Expected result:** All SSO members cleanly removed, no orphaned accounts
### Test 4: Mixed authentication scenario
**Setup:**
- Organization with both SSO and non-SSO members
- SSO members: employees (via SSO)
- Non-SSO members: contractors (password auth)
- Mixed owner types
**Test procedure:**
1. **Ensure non-SSO owner exists:**
- Verify at least one non-SSO owner
- Test their login before deletion
2. **Delete SSO provider:**
- System allows deletion (non-SSO owner exists)
- Confirm deletion
3. **Verify selective removal:**
- SSO members removed (employees)
- Non-SSO members retained (contractors)
- Organization still functional
- Non-SSO owners can manage organization
**Expected result:** ✅ Selective removal - only SSO members affected
### Safe deletion verification checklist
- [ ] Cannot delete without non-SSO owner account
- [ ] Error message clearly explains requirement
- [ ] Adding non-SSO owner enables deletion
- [ ] All SSO members removed upon deletion
- [ ] Non-SSO members unaffected by SSO provider deletion
- [ ] Organization remains accessible via non-SSO accounts
- [ ] SSO configuration completely removed after deletion
- [ ] Non-SSO owner account tested BEFORE deletion
### Best practices for safe deletion
**Before deleting SSO provider:**
1. **Create dedicated non-SSO owner account**
- Use password authentication
- **Test that this account can log in**
- Store credentials in secure password manager
- Verify owner permissions
2. **Communication plan:**
- Notify all SSO members before deletion
- Explain they will lose organization access
- Provide timeline for deletion
- Offer alternative access if needed (re-invite as non-SSO)
3. **Documentation:**
- Document which members will be removed
- Plan for re-adding users if needed
- Have rollback plan (reconfigure SSO if needed)
**After deletion:**
1. **Verify organization function:**
- Test non-SSO owner access
- Verify critical functionality works
- Check that SSO members removed
2. **User communication:**
- Confirm to users that deletion complete
- Provide instructions for alternative access
- Answer questions about regaining access
### Configuration issues
#### "SSO sign-in doesn't work at all"
Common causes:
- Metadata URL/file incorrect or expired
- Certificate expired (especially Google Workspace - check during setup)
- Attribute mapping misconfigured
- User not assigned to Supabase app in identity provider
- Email domain not configured in Supabase SSO settings
- User email domain doesn't match configured domains
**Troubleshooting steps:**
1. Verify metadata URL/file is accessible and current
2. Check certificate expiration date
3. Verify attribute mappings (email mapping is required)
4. Confirm user is assigned to app in IdP
5. Check domain configuration in Supabase matches user email
6. Review IdP logs for authentication errors
#### "Attribute mapping errors or missing user data"
**Requirements:**
- Email mapping to `email` is **required**
- Attribute keys must be spelled exactly as shown in provider
- Use provider presets (Okta, Azure, G Suite) to avoid errors
**Troubleshooting:**
1. Verify email attribute is mapped correctly
2. Check attribute names match your IdP configuration exactly
3. Test that mappings return expected user data
4. Use IdP test tools to see what attributes are being sent
#### "Cannot delete SSO provider"
**Error:** "At least one non-SSO account is required"
**Solution:**
1. Create or convert an existing member to a non-SSO owner account
2. Verify the non-SSO owner can log in
3. Then proceed with SSO provider deletion
**Why this is required:** Prevents complete organization lockout if SSO becomes unavailable
## Best practices
### Security and safety
#### CRITICAL: Maintain at least one non-SSO owner account
- **Required** to prevent complete organization lockout
- System enforces this when deleting SSO provider
- Create dedicated non-SSO owner **before** enabling SSO
- Store credentials securely in a password manager
- Verify this account can log in before critical changes
#### Monitor certificate expiration
- Set calendar reminders **30 days before** certificate expiration
- Especially important for Google Workspace (certificates shown during setup)
- Test SSO after certificate renewal
- Update metadata in Supabase after IdP certificate renewal
- Communicate planned renewal to team
#### Configure domains carefully
- Use specific corporate email domains only
- Public domains (gmail.com, yahoo.com, etc.) are automatically blocked
- Be cautious with domains you don't fully control
- Multiple domains supported for contractors/acquisitions
- Document which domains are configured and why
#### Regular access reviews
- Periodically review organization member list
- Verify auto-join role is still appropriate
- Check for orphaned or inactive accounts
- Coordinate with IT team on user access reviews
- Remove members who no longer need access
### Configuration and testing
#### Recommended SSO setup workflow
1. Create or verify non-SSO owner account exists
2. Configure SSO provider with auto-join **DISABLED**
3. Test SSO login with your own account
4. Verify attribute mappings are correct
5. Test with 2-3 additional users
6. Enable auto-join if desired
7. Test auto-join functionality thoroughly
8. Communicate SSO availability to team
#### Role selection for auto-join
- Default to **"Developer"** role (principle of least privilege)
- Avoid "Owner" or "Administrator" for auto-join
- Promote users individually as needed
- Review and document your access control strategy
- See [access control documentation](/docs/guides/platform/access-control) for role details
#### Attribute mapping
- Email mapping is **REQUIRED**
- Use provider presets (Okta, Azure, G Suite) when available
- Document custom mappings for future reference
- Test mappings return expected user data
- Keep mappings consistent across environments
#### Multi-environment strategy
- Consider separate providers for dev/staging/prod
- Test configuration changes in non-production first
- Keep provider configurations synchronized
- Document differences between environments
- See [Multiple SSO Providers guide](/docs/guides/platform/sso/multiple-providers) for details
### Operations and maintenance
#### Before making SSO changes
- Notify team members in advance
- Schedule during low-usage period if possible
- Have rollback plan ready
- Keep Supabase support contact information handy
- Document what you're changing and why
#### After SSO configuration changes
- Test login immediately
- Verify auto-join still works (if enabled)
- Check that invitations are working
- Confirm no users are locked out
- Monitor for support requests from team
#### Before deleting SSO provider
- Verify at least one non-SSO owner exists (system enforces)
- Understand that **all SSO members will be removed automatically**
- Communicate to affected users **before** deletion
- Consider disabling rather than deleting if temporary
- Have plan for users to regain access if needed
#### Coordinating with IT/Security team
- SSO changes may affect compliance requirements
- Certificate renewals require coordination
- User access reviews should include Supabase
- Incident response plans should consider SSO dependencies
- Document SSO configuration in your organization's runbook
## Final verification checklist
Before rolling out SSO to your organization:
**Authentication & Login Flows:**
- [ ] IdP-initiated login works from IdP dashboard
- [ ] SP-initiated login works (if domains configured)
- [ ] Appropriate login flow chosen for your use case
- [ ] Domain configuration correct (or intentionally empty for IdP-only)
- [ ] Multiple environments route correctly (if using multiple providers)
**Auto-Join Functionality:**
- [ ] Auto-join adds users to correct organization (if enabled)
- [ ] Auto-joined users receive correct default role
- [ ] Auto-join works on first login (not just signup)
- [ ] Existing users auto-join when feature enabled
- [ ] Auto-join is idempotent (no duplicate memberships)
- [ ] Auto-join works with IdP-initiated (no domains required)
- [ ] Non-matching domains excluded (if using SP-initiated)
**Invitations:**
- [ ] SSO-required invitations work correctly
- [ ] Non-SSO invitations work correctly
- [ ] Invitation types can be explicitly chosen
- [ ] SSO mismatch errors are clear
**Safety & Access Controls:**
- [ ] At least one non-SSO owner account exists
- [ ] Non-SSO owner account can log in successfully
- [ ] Non-SSO credentials stored securely
- [ ] SSO account deletion restrictions understood and tested
- [ ] Safe deletion behavior verified (if tested)
**Configuration:**
- [ ] Certificate expiration date documented with calendar reminders
- [ ] Team notified of SSO availability
- [ ] Login instructions provided (IdP tile and/or supabase.com)
- [ ] Rollback plan documented
- [ ] Support contact information available
**Testing Completed:**
- [ ] Tested with multiple user accounts
- [ ] Both login flows tested (if both enabled)
- [ ] Auto-join behavior verified
- [ ] SSO account restrictions confirmed
- [ ] Domain restrictions validated (if applicable)
- [ ] Multi-environment isolation verified (if using multiple providers)
## Need help?
If you encounter issues not covered in this guide, contact your Supabase support representative for assistance. When reaching out, include:
- Organization name and URL
- SSO provider type (Okta, Azure AD, Google Workspace, etc.)
- Specific error messages
- Steps you've already tried
- Whether the issue affects all users or specific individuals
apps/docs/public/img/sso-dashboard-enabled-idp.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 92 KiB

apps/studio/components/interfaces/Organization/SSO/SSOConfig.tsx
+141 -23
View File
@@ -13,6 +13,7 @@ import {
FormField_Shadcn_,
Switch,
} from 'ui'
import { Admonition } from 'ui-patterns'
import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
import { GenericSkeletonLoader } from 'ui-patterns/ShimmeringLoader'
import z from 'zod'
@@ -33,18 +34,18 @@ import { useOrgSSOConfigQuery } from '@/data/sso/sso-config-query'
import { useSSOConfigUpdateMutation } from '@/data/sso/sso-config-update-mutation'
import { useCheckEntitlements } from '@/hooks/misc/useCheckEntitlements'
import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
import { useStaticEffectEvent } from '@/hooks/useStaticEffectEvent'
import { DOCS_URL } from '@/lib/constants'
const FormSchema = z
.object({
enabled: z.boolean(),
domains: z
.array(
z.object({
value: z.string().trim().min(1, 'Please provide a domain'),
})
)
.min(1, 'At least one domain is required'),
enableSpInitiated: z.boolean(),
domains: z.array(
z.object({
value: z.string().trim(),
})
),
metadataXmlUrl: z.string().trim().optional(),
metadataXmlFile: z.string().trim().optional(),
emailMapping: z.array(z.object({ value: z.string().trim().min(1, 'This field is required') })),
@@ -54,6 +55,28 @@ const FormSchema = z
joinOrgOnSignup: z.boolean(),
roleOnJoin: z.string().optional(),
})
.superRefine((data, ctx) => {
if (!data.enableSpInitiated) return
const hasValidDomain = data.domains?.some((d) => d.value && d.value.trim().length > 0)
if (!hasValidDomain) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: 'At least one domain is required when SP-initiated login is enabled',
path: ['domains'],
})
}
data.domains?.forEach((d, idx) => {
if (!d.value || d.value.trim().length === 0) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: 'Please provide a domain',
path: ['domains', idx, 'value'],
})
}
})
})
// set the error on both fields
.refine((data) => data.metadataXmlUrl || data.metadataXmlFile, {
message: 'Please provide either a metadata XML URL or upload a metadata XML file',
@@ -68,6 +91,7 @@ export type SSOConfigFormSchema = z.infer<typeof FormSchema>
const defaultValues = {
enabled: false,
enableSpInitiated: false,
domains: [{ value: '' }],
metadataXmlUrl: '',
metadataXmlFile: '',
@@ -105,13 +129,24 @@ export const SSOConfig = () => {
})
const isSSOEnabled = form.watch('enabled')
const enableSpInitiated = form.watch('enableSpInitiated')
const { mutate: createSSOConfig, isPending: isCreating } = useSSOConfigCreateMutation({
onSuccess: () => form.reset(),
onSuccess: () => {
toast.success('Successfully created SSO configuration')
// Reset form to current values to mark as clean
// This allows useEffect to reset with fresh data when query refetches
form.reset(form.getValues())
},
})
const { mutate: updateSSOConfig, isPending: isUpdating } = useSSOConfigUpdateMutation({
onSuccess: () => form.reset(),
onSuccess: () => {
toast.success('Successfully updated SSO configuration')
// Reset form to current values to mark as clean
// This allows useEffect to reset with fresh data when query refetches
form.reset(form.getValues())
},
})
const [isDeleteModalVisible, setIsDeleteModalVisible] = useState(false)
@@ -136,7 +171,8 @@ export const SSOConfig = () => {
slug: organization!.slug,
config: {
enabled: values.enabled,
domains: values.domains.map((d) => d.value),
// Send empty array if SP-initiated is disabled
domains: values.enableSpInitiated ? values.domains.map((d) => d.value).filter(Boolean) : [],
metadata_xml_file: values.metadataXmlFile!,
metadata_xml_url: values.metadataXmlUrl!,
email_mapping: values.emailMapping.map((item) => item.value).filter(Boolean),
@@ -160,22 +196,46 @@ export const SSOConfig = () => {
deleteSSOConfig({ slug: organization.slug })
}
useEffect(() => {
if (ssoConfig) {
const syncFormFromConfig = useStaticEffectEvent(() => {
if (!organization?.slug) return
// Only reset form if it's not dirty (user hasn't made changes)
if (ssoConfig && !form.formState.isDirty) {
form.reset({
enabled: ssoConfig.enabled,
domains: ssoConfig.domains?.map((domain) => ({ value: domain })) ?? [],
// Infer SP-initiated from domains presence
enableSpInitiated: ssoConfig.domains && ssoConfig.domains.length > 0,
domains: ssoConfig.domains?.map((domain) => ({ value: domain })) || [],
metadataXmlUrl: ssoConfig.metadata_xml_url,
metadataXmlFile: ssoConfig.metadata_xml_file,
emailMapping: ssoConfig.email_mapping.map((email) => ({ value: email })),
userNameMapping: ssoConfig.user_name_mapping?.map((userName) => ({ value: userName })),
firstNameMapping: ssoConfig.first_name_mapping?.map((firstName) => ({ value: firstName })),
lastNameMapping: ssoConfig.last_name_mapping?.map((lastName) => ({ value: lastName })),
userNameMapping:
ssoConfig.user_name_mapping?.map((userName) => ({ value: userName })) || [],
firstNameMapping:
ssoConfig.first_name_mapping?.map((firstName) => ({ value: firstName })) || [],
lastNameMapping:
ssoConfig.last_name_mapping?.map((lastName) => ({ value: lastName })) || [],
joinOrgOnSignup: ssoConfig.join_org_on_signup_enabled,
roleOnJoin: ssoConfig.join_org_on_signup_role,
})
}
}, [ssoConfig, form])
})
useEffect(() => {
syncFormFromConfig()
}, [ssoConfig, organization?.slug, syncFormFromConfig])
// Automatically add an empty domain field when SP-initiated is enabled
const ensureDomainField = useStaticEffectEvent(() => {
const currentDomains = form.getValues('domains')
if (enableSpInitiated && (!currentDomains || currentDomains.length === 0)) {
form.setValue('domains', [{ value: '' }], { shouldValidate: false })
}
})
useEffect(() => {
ensureDomainField()
}, [enableSpInitiated, ensureDomainField])
return (
<ScaffoldContainer size="small" className="px-6 xl:px-10">
@@ -234,12 +294,63 @@ export const SSOConfig = () => {
/>
</CardContent>
{(isSSOEnabled || ssoConfig) && (
{isSSOEnabled && (
<>
<CardContent>
<SSODomains form={form} />
<FormField_Shadcn_
control={form.control}
name="enableSpInitiated"
render={({ field }) => (
<FormItemLayout
layout="flex-row-reverse"
label="Enable SP-initiated login"
description="Allow users to start the login flow from the Supabase dashboard by entering their email address. Requires configuring email domains below."
>
<FormControl_Shadcn_>
<Switch checked={field.value} onCheckedChange={field.onChange} />
</FormControl_Shadcn_>
</FormItemLayout>
)}
/>
{form.watch('enableSpInitiated') && (
<Admonition
type="note"
title="Understanding SSO login flows"
className="mt-4"
>
<div className="space-y-3 text-sm">
<div>
<strong>SP-initiated (Service Provider):</strong> Users start at
supabase.com, enter their email address, and are redirected to your
identity provider (Okta, Azure AD, etc.) for authentication.
Requires configuring email domains.
</div>
<div>
<strong>IdP-initiated (Identity Provider):</strong> Users click an
app tile or bookmark in your identity provider dashboard and are
directly authenticated into Supabase. Works automatically without
domain configuration.
</div>
<p className="text-foreground-lighter">
Most enterprises use IdP-initiated flow for its simplicity. Enable
SP-initiated only if you need users to start at supabase.com.{' '}
<InlineLink href={`${DOCS_URL}/guides/platform/sso#login-flows`}>
Learn more about SSO flows
</InlineLink>
.
</p>
</div>
</Admonition>
)}
</CardContent>
{form.watch('enableSpInitiated') && (
<CardContent>
<SSODomains form={form} />
</CardContent>
)}
<CardContent>
<SSOMetadata form={form} />
</CardContent>
@@ -303,16 +414,23 @@ export const SSOConfig = () => {
variant="destructive"
title="Delete SSO Provider"
loading={isDeleting}
confirmString={ssoConfig?.domains?.[0] ?? ''}
confirmPlaceholder="Type the domain above to confirm"
confirmString={ssoConfig?.domains?.[0] || organization?.slug || ''}
confirmPlaceholder={`Type ${ssoConfig?.domains?.[0] ? 'the first domain' : 'the organization slug'} to confirm`}
confirmLabel="I understand, delete SSO provider and members"
onConfirm={onDeleteSSOConfig}
onCancel={() => setIsDeleteModalVisible(false)}
>
<div className="space-y-3">
<p className="text-sm text-foreground-lighter">
You are about to delete the SSO provider for{' '}
<span className="text-foreground font-semibold">{ssoConfig?.domains?.[0]}</span>.
You are about to delete the SSO provider
{ssoConfig?.domains?.[0] && (
<>
{' '}
for{' '}
<span className="text-foreground font-semibold">{ssoConfig.domains[0]}</span>
</>
)}
.
</p>
{ssoMemberCount > 0 && (
apps/studio/components/interfaces/Organization/SSO/SSODomains.tsx
+77 -24
View File
@@ -1,32 +1,85 @@
import { useForm } from 'react-hook-form'
import { Plus, Trash } from 'lucide-react'
import { useFieldArray, useForm } from 'react-hook-form'
import {
Button,
FormControl_Shadcn_,
FormField_Shadcn_,
FormItem_Shadcn_,
FormMessage_Shadcn_,
Input_Shadcn_,
} from 'ui'
import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
import { SingleValueFieldArray } from 'ui-patterns/form/SingleValueFieldArray/SingleValueFieldArray'
import { SSOConfigFormSchema } from './SSOConfig'
export const SSODomains = ({ form }: { form: ReturnType<typeof useForm<SSOConfigFormSchema>> }) => {
const { fields, append, remove } = useFieldArray({
control: form.control,
name: 'domains',
})
const domainsError = form.formState.errors.domains
// Handle different error structures - could be root error or direct error
const arrayLevelError =
domainsError &&
typeof domainsError === 'object' &&
'message' in domainsError &&
typeof domainsError.message === 'string'
? domainsError.message
: domainsError &&
typeof domainsError === 'object' &&
'root' in domainsError &&
domainsError.root &&
typeof domainsError.root === 'object' &&
'message' in domainsError.root
? String(domainsError.root.message)
: null
return (
<FormItemLayout
label="Domains"
layout="flex-row-reverse"
description="Provide one or more domains"
>
<SingleValueFieldArray
control={form.control}
name="domains"
valueFieldName="value"
createEmptyRow={() => ({ value: '' })}
placeholder="example.com"
addLabel="Add another"
removeLabel="Remove domain"
minimumRows={1}
inputAutoComplete="off"
className="w-96"
rowsClassName="grid gap-2 w-full"
addButtonType="default"
addButtonSize="tiny"
addButtonClassName="w-auto"
/>
</FormItemLayout>
<>
<FormItemLayout
label="Email Domains"
layout="flex-row-reverse"
description="Users with these email domains will be redirected to your identity provider when logging in from Supabase."
>
<div className="grid gap-2 w-full">
{fields.map((field, idx) => (
<div key={field.id} className="flex gap-2 items-top">
<FormField_Shadcn_
name={`domains.${idx}.value`}
render={({ field }) => (
<FormItem_Shadcn_ className="flex-1">
<FormControl_Shadcn_>
<Input_Shadcn_ {...field} autoComplete="off" placeholder="example.com" />
</FormControl_Shadcn_>
<FormMessage_Shadcn_ />
</FormItem_Shadcn_>
)}
/>
<Button
type="default"
icon={<Trash size={12} />}
className="h-[34px] w-[34px]"
onClick={() => remove(idx)}
/>
</div>
))}
<div>
<Button
type="default"
icon={<Plus className="w-4 h-4" />}
size="tiny"
onClick={() => append({ value: '' })}
>
Add another
</Button>
</div>
{arrayLevelError && (
<p className="text-sm font-medium text-destructive">{arrayLevelError}</p>
)}
</div>
</FormItemLayout>
</>
)
}
supa-mdx-lint/Rule001HeadingCase.toml
+3
View File
@@ -22,6 +22,7 @@ may_uppercase = [
"AWS Marketplace",
"Azure",
"Azure Developers?",
"Azure MyApps",
"BigQuery",
"Bitbucket",
"Bitbucket Pipelines",
@@ -107,6 +108,7 @@ may_uppercase = [
"IPv6",
"IVFFlat",
"Iceberg",
"Identity Provider Initiated",
"IdP",
"Inbucket",
"Index Advisor",
@@ -201,6 +203,7 @@ may_uppercase = [
"Sentry",
"Server-Side Auth",
"Server-Side Rendering",
"Service Provider Initiated",
"Shared Pooler",
"Single Sign-On",
"Slack",
supa-mdx-lint/Rule003Spelling.toml
+6
View File
@@ -26,6 +26,7 @@ allow_list = [
"[Aa]uditability",
"[Aa]utomations?",
"[Aa]utovacuum(s|ing|ed)?",
"Azure MyApps",
"[Bb]ackend",
"[Bb]ackoff",
"[Bb]lockchains?",
@@ -194,9 +195,11 @@ allow_list = [
"Dinesh",
"Django",
"Docker",
"[Dd]omainless",
"dotenvx",
"Drizzle",
"ElevenLabs",
"[Ee]nablement",
"EnterpriseDB",
"Entra",
"ePHI",
@@ -236,6 +239,7 @@ allow_list = [
"Infisical",
"IntelliJ",
"IntelliSense",
"[Ii]nviter's",
"IOWait",
"IVFFlat",
"JetBrains",
@@ -322,7 +326,9 @@ allow_list = [
"Refine",
"[Rr]etryable",
"Roboflow",
"[Rr]ollout",
"Rollup",
"[Rr]unbook",
"SaaS",
"[Ss]avepoint",
"SDKs",