mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03: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
7.9 KiB
Plaintext
172 lines
7.9 KiB
Plaintext
---
|
|
title: 'Set Up SSO with Azure AD'
|
|
description: 'Configure single sign-on with Azure AD (Microsoft Entra).'
|
|
---
|
|
|
|
<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 Microsoft Azure AD.
|
|
|
|
## Step 1: Add and register an Enterprise application [#add-and-register-enterprise-application]
|
|
|
|
Open up the [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) dashboard for your Azure account.
|
|
|
|
Click the _Add_ button then _Enterprise application_.
|
|
|
|
|
|
|
|
## Step 2: Choose to create your own application [#create-application]
|
|
|
|
You'll be using the custom enterprise application setup for Supabase.
|
|
|
|
|
|
|
|
## Step 3: Fill in application details [#add-application-details]
|
|
|
|
In the modal titled _Create your own application_, enter a display name for Supabase. This is the name your Azure AD users will see when signing in to Supabase from Azure. `Supabase` works in most cases.
|
|
|
|
Make sure to choose the third option: _Integrate any other application you
|
|
don't find in the gallery (Non-gallery)_.
|
|
|
|
|
|
|
|
## Step 4: Set up single sign-on [#set-up-single-sign-on]
|
|
|
|
Before you get to assigning users and groups, which would allow accounts in Azure AD to access Supabase, you need to configure the SAML details that allows Supabase to accept sign in requests from Azure AD.
|
|
|
|
|
|
|
|
## Step 5: Select SAML single sign-on method [#saml-sso]
|
|
|
|
Supabase only supports the SAML 2.0 protocol for Single Sign-On, which is an industry standard.
|
|
|
|
|
|
|
|
## Step 6: Upload SAML-based sign-on metadata file [#upload-saml-metadata]
|
|
|
|
First you need to download Supabase's SAML metadata file. Click the button below to initiate a download of the file.
|
|
|
|
<a href="https://alt.supabase.io/auth/v1/sso/saml/metadata?download=true">
|
|
<Button size="large" icon={<IconArrowDown />}>
|
|
Download Supabase SAML Metadata File
|
|
</Button>
|
|
</a>
|
|
|
|
Alternatively, visit this page to initiate a download: `https://alt.supabase.io/auth/v1/sso/saml/metadata?download=true`
|
|
|
|
Click on the _Upload metadata file_ option in the toolbar and select the file you just downloaded.
|
|
|
|
|
|
|
|
All of the correct information should automatically populate the _Basic SAML Configuration_ screen as shown.
|
|
|
|
|
|
|
|
**Make sure you input these additional settings.**
|
|
|
|
| Setting | Value |
|
|
| ----------- | -------------------------------------------- |
|
|
| Sign on URL | `https://supabase.com/dashboard/sign-in-sso` |
|
|
| Relay State | `https://supabase.com/dashboard` |
|
|
|
|
Finally, click the _Save_ button to save the configuration.
|
|
|
|
## Step 7: Obtain metadata URL [#idp-metadata-url]
|
|
|
|
Save the link under **App Federation Metadata URL** in \*section 3 **SAML Certificates\***. You will need to enter this URL later in [Step 10](#dashboard-configure-metadata).
|
|
|
|
|
|
|
|
## Step 8: 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 9: 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">
|
|
|
|
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:
|
|
|
|
|
|
|
|
## Step 11: Configure attribute mapping [#dashboard-configure-attributes]
|
|
|
|
Fill out the Attribute Mapping section using the **Azure** preset.
|
|
|
|
|
|
|
|
## Step 12: Join organization on signup (optional) [#dashboard-configure-autojoin]
|
|
|
|
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">
|
|
|
|
Read [the Access Control documentation](/docs/guides/platform/access-control) for details about each role.
|
|
|
|
</Admonition>
|
|
|
|
## 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.
|
|
|
|
## Step 14: Test your SSO configuration
|
|
|
|
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>
|