# Set Up SSO with Okta

Configure single sign-on with Okta.

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.

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

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

![Okta dashboard: Create App Integration button](/docs/img/sso-okta-step-01.png)

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

![Okta dashboard: Create new app integration dialog](/docs/img/sso-okta-step-02.png)

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

![Okta dashboard: Create SAML Integration wizard](/docs/img/sso-okta-step-03.png)

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

![Okta dashboard: Create SAML Integration wizard, Configure SAML step](/docs/img/sso-okta-step-04.png)

## 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).

![Okta dashboard: Attribute Statements configuration screen](/docs/img/sso-okta-step-05.png)

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

![Okta dashboard: SAML Signing Certificates, Actions button highlighted](/docs/img/sso-okta-step-06.png)

## Step 7: Enable SSO in the Dashboard [#dashboard-enable-sso]

1. Visit the [SSO tab](/dashboard/org/_/sso) under the Organization Settings page. ![SSO disabled](/docs/img/sso-dashboard-disabled.png)

2. Toggle **Enable Single Sign-On** to begin configuration. Once enabled, the configuration form appears. ![SSO enabled](/docs/img/sso-dashboard-enabled.png)

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

![Domain configuration](/docs/img/sso-dashboard-configure-domain.png)

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.

![Domain configuration with multiple domains](/docs/img/sso-dashboard-configure-domain-multi.png)

We do not permit use of public domains like `gmail.com`, `yahoo.com`.

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

## Step 9: Configure metadata [#dashboard-configure-metadata]

Enter the metadata URL you obtained from [Step 6](#idp-metadata-url) into the Metadata URL field:

![Metadata configuration with Okta](/docs/img/sso-dashboard-configure-metadata-okta.png)

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

![Attribute mapping configuration](/docs/img/sso-dashboard-configure-attributes.png)

If you did not customize your settings you may save some time by clicking the **Okta** preset.

## Step 11: Join organization on signup (optional) [#dashboard-configure-autojoin]

**Recommended workflow:** Start with auto-join **disabled** to test your SSO configuration. Once SSO login is working correctly, enable auto-join if desired.

By default this setting is disabled, users logging in via SSO will not be added to your organization automatically.

![Auto-join disabled](/docs/img/sso-dashboard-configure-autojoin-disabled.png)

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.

![Auto-join enable](/docs/img/sso-dashboard-configure-autojoin-enabled.png)

When auto-join is enabled, you can choose the **default role** for new users:

![Auto-join role selection](/docs/img/sso-dashboard-configure-autojoin-enabled-role.png)

We recommend choosing **Developer** as the default role (principle of least privilege) and promoting users individually as needed.

Visit [access-control](/docs/guides/platform/access-control) documentation for details about each role.

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

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

**Testing in Okta sandbox:** If your organization has an Okta sandbox environment, consider testing your SSO configuration there first before applying to production.