# Source: https://planetscale.com/docs/security/sso.md

# Single sign-on

> Single sign-on (SSO) provides additional account security by allowing company administrators to require the use of an identity provider when logging into PlanetScale.

## Overview

Users only need to sign in once with a single set of credentials *(i.e. password and email)* to access all of their tools and applications upon joining the company.

Furthermore, SSO allows an administrator to revoke someone’s access to all tools and applications from a single place when they leave a team or the company. PlanetScale uses SAML SSO.

<Note>
  SSO is available as an *add-on* for Scaler Pro plan at \$199/month per organization and included in our [Enterprise plans](/docs/planetscale-plans#planetscale-enterprise-plan). Security is important to us, so we do not profit off of SSO. We only charge enough to cover the WorkOS cost for enrolling a new account.
</Note>

## Implications

It's important to understand how enabling SSO will affect your Organization. Once enabled, the following will happen:

* All non-admin members will be removed from the organization.
* [Organization Administrators](/docs/security/access-control#organization-administrator) will remain in the Organization so they can configure SSO without losing access.
  * All administrators will retain access with their old credentials, until they logout and login through their Identity Provider. Once they've authenticated through their Identity Provider the account will only be usable with SSO authentication.
* Each [Organization Member](https://app.planetscale.com/planetscale/settings/members) must re-authenticate using SSO. Once they've authenticated, they will be automatically added back to the organization.
* Organization Member invites will be disabled when SSO is enabled; all Organization Membership will be managed through SSO.
* Organization Members that were [Database Administrators](/docs/security/access-control#database-administrator) before will no longer have that role upon rejoining. You must assign them the role after they re-authenticate with SSO.
* Organization Members that were on [Teams](/docs/security/teams) will need to be re-added.
* Any database credentials and tokens that were generated by non-admin members will remain active, so you **do not need to regenerate connection credentials**.
* Organization Members removed from your SSO, will still appear in the Organization until they are manually removed.
  * While they are visible in the Organization they will not be able to authenticate to PlanetScale.
  * If you enabled [Directory Sync](/docs/security/#directory-sync), the Member will be removed from the Organization without manual intervention.

<Note>
  If you enable SSO and Directory Sync, the Directory will remain the source of truth, and Teams will map accordingly. Please see the [Directory Sync](/docs/security/#directory-sync) section for more information.
</Note>

## Enable SSO for your organization

To enable SSO for your organization, you must be an [Organization Administrator](/docs/security/access-control). Organization administrators can *enable*, *configure*, and *disable* SSO for all members of your organization.

First, head to your [PlanetScale organization's authentication page](https://app.planetscale.com/~/settings/authentication) under Settings -> Authentication. Type in the email domains that you would like to allow to sign in through SSO, and click "Enable single sign-on".

You can configure your SSO settings by clicking the "identity provider" link on that SSO settings page. This will take you to WorkOS where you can choose your identity provider. You can find documentation for your specific identity provider in the [WorkOS integrations documentation](https://workos.com/docs/integrations).

You also have the option to manage PlanetScale roles through your identity provider's SSO profile. Just check the box next to that message on the settings page to enable.

## Multiple organizations with SSO

You can enable SSO for multiple organizations using the same identity provider. However, users across all your organizations must have unique internal IDs within your identity provider.

For example, if your identity provider has a user with:

* Email: `user@example.com`
* Internal ID: `some_user_id`

You cannot create another user with:

* Email: `user+staging@example.com`
* Internal ID: `some_user_id` (same as above)

This restriction exists because both email addresses would be treated as the same user due to the identical internal ID, which could cause authentication conflicts across organizations.

After enabling SSO for a different organization, you will be able to join the new organization by logging out and using the Single Sign On form to log into the new organization for the first time.

## Disable SSO

When SSO is disabled for an organization, users can log in with the password they initially set for their PlanetScale account. If they don't know their password, users can go through the password reset flow to regain access to their account.

Should a user lose access to the email address associated with that organization, they'll also lose access to their account after SSO is disabled.

## Directory Sync

We also support the use of Directory Sync with SSO. You can use Directory Sync to make the directory the source of truth for organization membership.

### Enable Directory Sync

To enable Directory Sync, you first must have SSO enabled.

Once enabled, go to your Organization settings page, click "**Authentication**", and click the "**Enable directory sync**" button.

You can now configure Directory Sync using your identity provider.

### Directory Sync access control

Directory Sync automatically adds and removes members from your PlanetScale organization to match your SSO directory. If you have groups defined within your SSO provider, it can also automatically create [Teams](/docs/security/teams) within your PlanetScale organization mapped to those groups.

If you wish to have your identity provider determine user roles in PlanetScale, please make sure to select the option for `Manage PlanetScale roles through identity provider` in Settings > Authentication.

<Frame>
  <img src="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=e5692ad5b294f96fd1104f85bc6ec4f0" alt="Manage roles" data-og-width="1698" width="1698" data-og-height="372" height="372" data-path="docs/images/assets/docs/concepts/sso/sync.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=280&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=62212f4a6788cb68ab3967144eeb3589 280w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=560&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=96640d0f45789ea088dda7d83faa9424 560w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=840&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=d66e90cb0d0b7e97aa966f43692ca849 840w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=1100&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=5e0f63b77bc24f8a2960bcfefbfc3825 1100w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=1650&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=53fd9a76b5309080974134c2d1fa3852 1650w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/sync.png?w=2500&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=3343c9060d6d8289cd4ed4c7f77e8fbb 2500w" />
</Frame>

<Note>
  Once you enable Directory Sync, existing Teams will be cleared, as all Teams must map to a Directory group.
</Note>

Once you enable Directory Sync, existing Teams will be cleared, as all Teams must map to a Directory group.

You can find the directory-managed members under "**Settings**" > "**Members**", and directory-managed Teams under "**Settings**" > "**Teams**".

<Frame>
  <img src="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=ea6e8a6fedd17bed9a398d4c4d20e626" alt="Dashboard UI - Directory-managed Teams page" data-og-width="1800" width="1800" data-og-height="1392" height="1392" data-path="docs/images/assets/docs/concepts/sso/managed.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=280&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=fdfc6d5163dd5b23a8d6971a86f20e16 280w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=560&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=d8ad85a927fcfd4d0d5d14179714a681 560w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=840&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=2fa39492d377c6acce22cb0bfaca0543 840w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=1100&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=25d11d732a3c830f28c921fc73cf7182 1100w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=1650&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=0a8170a05664fddda91741021d1a4fd1 1650w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/managed.png?w=2500&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=ec15613c1c96e61e5787255432b6baee 2500w" />
</Frame>

## Using Okta to manage organization admins

There are two different ways to configure Okta to manage the user's role in a PlanetScale organization. The first approach uses SAML assertions during Single Sign On to update the role just-in-time. The second approach uses an attribute defined on the directory user to update the role in real time as it changes. It is up to user to decide which approach works best for their organization.

### Managing roles during single sign-on (SAML)

In order to update roles using SAML, you will first need to configure the SAML application and user profile in Okta before enabling the setting within PlanetScale.

#### Configuring the SAML Okta application

<Steps>
  <Step>
    Click the **Applications** > **Applications** in the Okta dashboard's sidebar.
  </Step>

  <Step>
    Find your PlanetScale SAML application that you configured earlier for WorkOS and find the **SAML Settings** section. Click on the **Edit** link in this section.
  </Step>

  <Step>
    In the **Configure SAML** step, find the **Attribute Statements (optional)** section, which defines the attributes of email, first and last name, and id.
  </Step>

  <Step>
    Add a new Attribute Statement with the following values.

    * Name — `planetscale_role`
    * Name Format — `Unspecified`
    * Value — `user.planetscale_role`
  </Step>
</Steps>

#### Creating user profile attributes

In order to define the custom attribute in Okta, you must update the default User profile to have the `planetscale_role` attribute.

<Steps>
  <Step>
    Click **Directory** > **Profile Editor** in the Okta dashboard's sidebar.
  </Step>

  <Step>
    Click the **User (default)** profile within Okta
  </Step>

  <Step>
    Click **Add attribute** and fill in the following values

    * Data type: `string`
    * Display name: `PlanetScale Role`
    * Variable name: `planetscale_role`
    * Enum: Enable the **Define enumerated list of values** checkbox and add these attributes:
      * Display name: `Member`, Value: `member`
      * Display name: `Administrator`, Value: `administrator`
  </Step>

  <Step>
    Click **Save attribute**
  </Step>
</Steps>

#### Enable in PlanetScale

Lastly, we will have to enable role management via SSO within the PlanetScale application.

<Steps>
  <Step>
    Go to your SSO organization's settings page
  </Step>

  <Step>
    Click on **Authentication** in the side navigation
  </Step>

  <Step>
    Check the **Manage PlanetScale roles through identity provider's SSO profile** checkbox
  </Step>
</Steps>

After following all of these steps, after you change the PlanetScale role for a user in Okta, their role will be updated accordingly the next time they log in via Single Sign On. If the role is changed during an active session, they will need to log out and log back in for it to be updated once again.

### Managing roles using Directory Sync (SCIM)

In order to manage roles using Directory Sync, you must properly configure the SCIM user's profile within Okta and update the Directory Sync custom attributes before enabling the setting within the PlanetScale dashboard.

#### Configuring the SCIM user profile

<Steps>
  <Step>
    Click **Directory** > **Profile Editor** in the Okta dashboard's sidebar.
  </Step>

  <Step>
    Click the user profile that maps to your SCIM application, it should be in the format of **\< SCIM application name > User**
  </Step>

  <Step>
    Click **Add attribute** and fill in the following values

    * Data type: `string`
    * Display name: `PlanetScale Role`
    * Variable name: `planetscale_role`
    * External name: `planetscale_role`
    * The External namespace should be defined as `urn:ietf:params:scim:schemas:core:2.0:User`.
    * Check the box to define an enumerated list of values, add the following:
      * Display name: `member`, Value: `member`
      * Display name: `administrator`, Value: `admin`
  </Step>

  <Step>
    Click **Save attribute**
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=330d20aa2c39a54e704af671aa573155" alt="PlanetScale Role" data-og-width="1678" width="1678" data-og-height="1536" height="1536" data-path="docs/images/assets/docs/concepts/sso/planetscale_role.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=280&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=75233fbe45e1c778db8ad7026a0c9242 280w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=560&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=6adf3487a2b89a13ca8297c406c50bc6 560w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=840&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=fb0c7c14481ca4a4ac355035d4a3a65f 840w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=1100&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=d841b2a2e4a9bcce4f017df4ab97f797 1100w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=1650&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=1d58a2757d47b6e266198369c6faaa29 1650w, https://mintcdn.com/planetscale-cad1a68a/dVvNdxOWlcjFg3oF/docs/images/assets/docs/concepts/sso/planetscale_role.png?w=2500&fit=max&auto=format&n=dVvNdxOWlcjFg3oF&q=85&s=0255c222c229300bb13c8bfbed9a02c4 2500w" />
</Frame>

This attribute then needs to be mapped to the PlanetScale application in Okta.

<Steps>
  <Step>
    Open the PlanetScale SCIM application in Okta Admin Console, then select Provisioning
  </Step>

  <Step>
    Scroll down to the bottom of the `Okta to App` provisioning page, and click `Show unmapped attributes`.
  </Step>

  <Step>
    Find `planetscale_role` and click the 🖋️ to map the attribute.
  </Step>

  <Step>
    Select `Map from Okta Profile` as the type and `planetscale_role` as the string.
  </Step>

  <Step>
    Save with Create & Update permission.
  </Step>
</Steps>

#### Configuring custom attributes within WorkOS

Next, you will need to update your WorkOS configuration to detect the custom attribute mappings.

<Steps>
  <Step>
    Go to the **Authentication** within your organization settings page.
  </Step>

  <Step>
    In the **Directory sync** section, click the `identity provider` link to open up the directory configuration page
  </Step>

  <Step>
    Click the **Edit Attribute Map** button and in the form, enter the folllowing:

    * Directory Provider Value: `planetscale_role`
    * PlanetScale Attribute: `planetscale_role`
  </Step>

  <Step>
    Click **Save mappings**
  </Step>
</Steps>

#### Enable in PlanetScale

Lastly, we will have to enable role management via SSO within the PlanetScale application.

<Steps>
  <Step>
    Go to your SSO organization's settings page
  </Step>

  <Step>
    Click on **Authentication** in the side navigation
  </Step>

  <Step>
    Check the **Manage PlanetScale roles through identity provider's directory** checkbox
  </Step>
</Steps>

After following all of these steps, after you change the PlanetScale role for a user in Okta, their role will be updated in PlanetScale without needing to re-authenticate.

## Need help?

Get help from [the PlanetScale Support team](https://support.planetscale.com/), or join our [GitHub discussion board](https://github.com/planetscale/discussion/discussions) to see how others are using PlanetScale.


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://planetscale.com/llms.txt