mirror of
https://github.com/supabase/supabase.git
synced 2026-06-05 04:12:29 +08:00
a3e71ba888
Implements comprehensive IdP-initiated login flow support, enabling organizations to configure SSO without email domains and support multiple SAML apps under the same domain (e.g., Dev/Staging/Prod environments). - Add "Enable SP-initiated login" toggle to SSOConfig.tsx - IdP-initiated flow is now always available (default) - SP-initiated flow is opt-in with domain requirement - Clear in-UI documentation explaining both flows - Make domains optional (only required when SP-initiated enabled) - Add form validation: domains required only if SP-initiated is ON - Fix org-switching bug: form now resets when switching organizations - Add organization.slug to useEffect dependencies - Prevent stale SSO config data from previous org being displayed - **IdP-initiated flow**: Users start login from identity provider dashboard - No domain configuration required - Enables multiple SAML apps per domain - Recommended default for enterprises - **SP-initiated flow**: Users start login at supabase.com (opt-in) - Requires email domain configuration - Maintains backward compatibility - **Both flows**: Can be enabled simultaneously for flexible access - Organizations can now create separate SSO providers for Dev/Staging/Prod - Each environment = separate SAML app in IdP - All using same email domain (e.g., company.com) - Users access via different IdP app tiles - No domain conflicts or subdomain requirements - Add 4 pages to SSO sidebar menu in NavigationMenu.constants.ts: - Understanding Login Flows (existing, now visible) - Choosing a Login Flow (existing, now visible) - Multiple SSO Providers (NEW comprehensive guide) - Testing and Best Practices (existing, now visible) Create comprehensive guide covering: - Multi-environment patterns (Dev/Staging/Prod with same domain) - Team separation, migration, and acquisition scenarios - Step-by-step setup for domainless providers - User access management and IDP app assignment strategies - Configuration synchronization and best practices - Troubleshooting common multi-provider issues Major expansion of testing-best-practices.mdx: - Fix outdated assumptions (domains no longer always required) - Add comprehensive login flow testing section: - IdP-initiated testing (no domains) - SP-initiated testing (with domains) - Domainless provider testing (multi-environment pattern) - Enhance auto-join testing with 8 detailed test phases: - Idempotency testing (no duplicate memberships) - Domainless configuration testing - Re-enablement testing (works on every login) - Add SSO account restrictions testing section - Add safe provider deletion testing with 4 test scenarios - Reorganize final checklist into 6 categorized sections Update azure.mdx, gsuite.mdx, okta.mdx: - Remove all "(coming soon)" references - Add guidance recommending IdP-initiated for multi-environment setups - Clarify domains are optional for IdP-initiated flow - Link to new Multiple SSO Providers guide **Domain Handling:** - Domains now optional in SSO provider configuration - Backend: `z.array(...).optional().default([])` - UI: Domains only required when SP-initiated toggle is ON - Empty array sent to API when SP-initiated disabled **Login Flow Logic:** - IdP-initiated: Always available, uses SAML assertion directly - SP-initiated: Requires domain lookup, opt-in only - Both flows can coexist with same SSO provider **Multi-Provider Support:** - Each provider has unique ACS URL - No domain conflicts (IdP-initiated doesn't check domains) - Enables unlimited providers per email domain - **Simplifies SSO setup**: No domain configuration needed by default - **Enables multi-environment**: Dev/Staging/Prod under same domain - **Improves UX**: One-click login from IdP dashboard - **Maintains compatibility**: SP-initiated still available as opt-in - **Better documentation**: Comprehensive guides for all scenarios ## UI ### SSO Disabled <img width="742" height="329" alt="sso-disabled" src="https://github.com/user-attachments/assets/73387777-181c-4206-9798-36f0d0790e4e" /> ### SSO Enabled - IdP-inititated (DEFAULT) <img width="742" height="1059" alt="sso-enabled-idp" src="https://github.com/user-attachments/assets/c189e08f-7642-4183-8853-dd5150b8a191" /> ### SSO Enabled - SP-intitiated <img width="727" height="1366" alt="sso-enabled-sp" src="https://github.com/user-attachments/assets/be5ad6dc-4803-446b-ae02-9edcbb5f42cd" /> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive guides for SSO login flow selection, testing best practices, and configuring multiple providers * Updated provider-specific setup documentation (Okta, Azure, Google Workspace) with refined workflows and testing recommendations * **New Features** * Enhanced SSO configuration interface with SP-initiated login toggle and improved email domain management for flexible authentication flows <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Chris Stockton <chris.stockton@supabase.io> Co-authored-by: Chris Chinchilla <chris.ward@supabase.io> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Chris Chinchilla <chris@chrischinchilla.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
172 lines
8.1 KiB
Plaintext
172 lines
8.1 KiB
Plaintext
---
|
|
title: 'Set Up SSO with Okta'
|
|
description: 'Configure single sign-on with Okta.'
|
|
---
|
|
|
|
<Admonition type="note">
|
|
|
|
This feature is only available on the [Team and Enterprise Plans](/pricing). If you are an existing Team or Enterprise Plan customer, continue with the setup below.
|
|
|
|
</Admonition>
|
|
|
|
<Admonition type="tip">
|
|
|
|
Looking for docs on how to add Single Sign-On support in your Supabase project? Head on over to [Single Sign-On with SAML 2.0 for Projects](/docs/guides/auth/enterprise-sso/auth-sso-saml).
|
|
|
|
</Admonition>
|
|
|
|
Supabase supports single sign-on (SSO) using Okta.
|
|
|
|
## Step 1: Choose to create an app integration in the applications dashboard [#create-app-integration]
|
|
|
|
Navigate to the Applications dashboard of the Okta admin console. Click _Create App Integration_.
|
|
|
|
|
|
|
|
## Step 2: Choose SAML 2.0 in the app integration dialog [#create-saml-app]
|
|
|
|
Supabase supports the SAML 2.0 SSO protocol. Choose it from the _Create a new app integration_ dialog.
|
|
|
|
|
|
|
|
## Step 3: Fill out general settings [#add-general-settings]
|
|
|
|
The information you enter here is for visibility into your Okta applications menu. You can choose any values you like. `Supabase` as a name works well for most use cases.
|
|
|
|
|
|
|
|
## Step 4: Fill out SAML settings [#add-saml-settings]
|
|
|
|
These settings let Supabase use SAML 2.0 properly with your Okta application. Make sure you enter this information exactly as shown on in this table.
|
|
|
|
| Setting | Value |
|
|
| ---------------------------------------------- | --------------------------------------------------- |
|
|
| Single sign-on URL | `https://alt.supabase.io/auth/v1/sso/saml/acs` |
|
|
| Use this for Recipient URL and Destination URL | ✔️ |
|
|
| Audience URI (SP Entity ID) | `https://alt.supabase.io/auth/v1/sso/saml/metadata` |
|
|
| Default `RelayState` | `https://supabase.com/dashboard` |
|
|
| Name ID format | `EmailAddress` |
|
|
| Application username | Email |
|
|
| Update application username on | Create and update |
|
|
|
|
|
|
|
|
## Step 5: Fill out attribute statements [#add-attribute-statements]
|
|
|
|
Attribute Statements allow Supabase to get information about your Okta users on each login.
|
|
|
|
**A `email` to `user.email` statement is required.** Other mappings shown below are optional and configurable depending on your Okta setup. If in doubt, replicate the same config as shown. You will use this mapping later in [Step 10](#dashboard-configure-attributes).
|
|
|
|
|
|
|
|
## Step 6: Obtain IdP metadata URL [#idp-metadata-url]
|
|
|
|
Supabase needs to finalize enabling single sign-on with your Okta application.
|
|
|
|
To do this scroll down to the _SAML Signing Certificates_ section on the _Sign On_ tab of the _Supabase_ application. Pick the _SHA-2_ row with an _Active_ status. Click on the _Actions_ dropdown button and then on the _View IdP Metadata_.
|
|
|
|
This will open up the SAML 2.0 Metadata XML file in a new tab in your browser. You will need to enter this URL later in [Step 9](#dashboard-configure-metadata).
|
|
|
|
The link usually has this structure: `https://<okta-org>.okta.com/apps/<app-id>/sso/saml/metadata`
|
|
|
|
|
|
|
|
## Step 7: Enable SSO in the Dashboard [#dashboard-enable-sso]
|
|
|
|
1. Visit the [SSO tab](/dashboard/org/_/sso) under the Organization Settings page. 
|
|
|
|
2. Toggle **Enable Single Sign-On** to begin configuration. Once enabled, the configuration form appears. 
|
|
|
|
## Step 8: Configure domains [#dashboard-configure-domain]
|
|
|
|
Enter one or more domains associated with your users email addresses (e.g., `supabase.com`).
|
|
These domains determine which users are eligible to sign in via SSO.
|
|
|
|
|
|
|
|
If your organization uses more than one email domain - for example, `supabase.com` for staff and `supabase.io` for contractors - you can add multiple domains here. All listed domains will be authorized for SSO sign-in.
|
|
|
|
|
|
|
|
<Admonition type="note">
|
|
|
|
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:
|
|
|
|
|
|
|
|
## Step 10: Configure attribute mapping [#dashboard-configure-attributes]
|
|
|
|
Enter the SAML attributes you filled out in [Step 5](#add-attribute-statements) into the Attribute Mapping section.
|
|
|
|
|
|
|
|
<Admonition type="note">
|
|
|
|
If you did not customize your settings you may save some time by clicking the **Okta** preset.
|
|
|
|
</Admonition>
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
When auto-join is enabled, you can choose the **default role** for new users:
|
|
|
|
|
|
|
|
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.
|
|
|
|
</Admonition>
|
|
|
|
## 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.
|
|
|
|
<Admonition type="tip">
|
|
|
|
**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>
|