SSO Testing and Best Practices

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
• 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 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.

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
   • 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
   • 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

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
   • 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#

Recommended testing workflow#

1. Start with auto-join disabled:

   • Navigate to SSO settings
   • 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
   • 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:

   This test is critical if you're using multiple environments under the same domain. See Multiple SSO Providers for details.

• 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#

Creating and testing invitations#

1. Create SSO-required invitation:

   • Navigate to organization team settings
   • 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

Testing SSO account restrictions#

SSO accounts have specific restrictions to prevent accidental organization lockouts.

Testing SSO account deletion restrictions#

1. Log in with SSO account:

   • Authenticate via SSO (IdP or SP-initiated)
   • Navigate to SSO settings
   • 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

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#

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
   • Confirm all owners are SSO accounts
   • No non-SSO owner exists

2. Attempt deletion:

   • Navigate to SSO settings
   • 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)#

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
   • Delete SSO provider
   • Confirm deletion

2. Verify deletion results:

   • All SSO members removed from organization
   • Check team settings
   • 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 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 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