apps/docs/content/guides/platform/sso/testing-best-practices.mdx
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.
Before you begin testing, verify:
Before testing auto-join and other features, verify which login flows work for your SSO configuration. See Understanding SSO Login Flows for technical details.
IdP-initiated login is always available and doesn't require domain configuration. This should be your primary test.
Test procedure:
Access from identity provider:
Verify authentication:
Confirm success:
Expected results:
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:
Test procedure:
Start at Supabase:
Enter email:
Verify redirect chain:
Test domain matching:
Expected results:
This is a critical test for domainless providers, which enable multiple SAML apps per domain.
Test scenario:
You've configured SSO with:
Test procedure:
Verify SP-initiated is unavailable:
Verify IdP-initiated works:
Confirm multi-environment pattern works (if applicable):
Expected results:
Multiple environments: If you're setting up Dev/Staging/Prod, this domainless pattern is recommended. See Multiple SSO Providers for detailed configuration guidance.
</Admonition>Navigate to the SSO sign-in page:
Enter your email address:
Verify redirect to identity provider:
Confirm successful sign-in:
Test with 2-3 additional users to verify:
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>Start with auto-join disabled:
Enable auto-join after successful test:
Test auto-join with your account:
Test with additional users:
/dashboard/org/_/teamTest domain restrictions (if using SP-initiated):
Test idempotency (prevents duplicate memberships):
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 for details.
</Admonition>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>Create SSO-required invitation:
Create non-SSO invitation:
Test SSO mismatch scenario:
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.
</Admonition>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>Log in with SSO account:
Attempt to delete SSO provider:
Verify other SSO operations work:
Expected results:
Log in with non-SSO owner:
Verify deletion capability:
Expected results:
Based on customer pain points that previously required support intervention:
Common workflow that causes this:
Solution:
Previous limitation:
Solution:
Cause: User is logged in with wrong authentication method for the invitation
Solution:
Recent safety improvements:
Best practice:
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>When an SSO provider is deleted:
This behavior prevents "orphaned" SSO accounts that can no longer authenticate.
Setup:
Test procedure:
Verify current state:
Attempt deletion:
Verify organization state:
Expected result: ❌ Deletion blocked with clear error message
Warning: This test WILL remove all SSO members. Only perform in test organizations.
</Admonition>Setup:
Add non-SSO owner:
Document SSO members:
Test procedure:
Attempt deletion as non-SSO owner:
Verify deletion results:
Verify non-SSO access:
Expected result: ✅ Deletion succeeds, SSO members removed, non-SSO access preserved
Test in isolated environment with test accounts.
Setup:
Test procedure:
Track members before deletion:
Delete SSO provider:
Verify member removal:
Expected result: All SSO members cleanly removed, no orphaned accounts
Setup:
Test procedure:
Ensure non-SSO owner exists:
Delete SSO provider:
Verify selective removal:
Expected result: ✅ Selective removal - only SSO members affected
Before deleting SSO provider:
Create dedicated non-SSO owner account
Communication plan:
Documentation:
After deletion:
Verify organization function:
User communication:
Common causes:
Troubleshooting steps:
Requirements:
email is requiredTroubleshooting:
Error: "At least one non-SSO account is required"
Solution:
Why this is required: Prevents complete organization lockout if SSO becomes unavailable
Before rolling out SSO to your organization:
Authentication & Login Flows:
Auto-Join Functionality:
Invitations:
Safety & Access Controls:
Configuration:
Testing Completed:
If you encounter issues not covered in this guide, contact your Supabase support representative for assistance. When reaching out, include: