mirror of
https://github.com/supabase/supabase.git
synced 2026-05-22 17:00:43 +08:00
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated SSO platform and testing guides by converting interactive checklists into plain bullet lists. * Preserved all checklist content and ordering (pre-configuration, login flow, auto-join, invitations, SSO restrictions, safe deletion, rollout, configuration drift). * Formatting-only changes to docs; no behavioral, API, or public-interface modifications. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
845 lines
28 KiB
Plaintext
845 lines
28 KiB
Plaintext
---
|
|
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
|