Skip to content

Single sign-on

Enable single sign-on (SSO) for increased account security.

Overview

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

Note

SSO is available as an add-on for Scaler Pro plan and included in our Enterprise plans.

Enable SSO for your organization

PlanetScale uses SAML SSO. Contact us to enable SSO for your organization.

Setup and 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 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 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 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 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, 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 section for more information.

After SSO has been enabled for your account, you can configure it under your PlanetScale organization settings.

Organization administrators can enable, configure, and disable SSO for all members of your organization.

Users can create multiple PlanetScale organizations (i.e. work, personal, etc.), using the same email address, but that email address can only be associated with one SSO-enabled organization.

Disabling SSO

When SSO is disabled for an organization, users can login 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 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.

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

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

  • Click the Applications > Applications in the Okta dashbaord's sidebar.
  • 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.
  • In the Configure SAML step, find the Attribute Statements (optional) section, which defines the attributes of email, first and last name, and id.
  • Add a new Attribute Statement with the following values.
    • Name — planetscale_role
    • Name Format — Unspecified
    • Value — user.planetscale_role

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.

  • Click Directory > Profile Editor in the Okta dashboard's sidebar.
  • Click the User (default) profile within Okta
  • 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
  • Click Save attribute

Enable in PlanetScale

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

  • Go to your SSO organization's settings page
  • Click on Authentication in the side navigation
  • Check the Manage PlanetScale roles through identity provider's SSO profile checkbox

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 PlanteScale dashboard.

Configuring the SCIM user profile

  • Click Directory > Profile Editor in the Okta dashboard's sidebar.
  • Click the user profile that maps to your SCIM application, it should be in the format of <SCIM application name> User
  • 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
  • Click Save attribute

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

  • Open the PlanetScale SCIM application in Okta Admin Console, then select Provisioning
  • Scroll down to the bottom of the Okta to App provisioning page, and click Show unmapped attributes.
  • Find planetscale_role and click the 🖋️ to map the attribute.
  • Select Map from Okta Profile as the type and planetscale_role as the string.
  • Save with Create & Update permission.

Configuring custom attributes within WorkOS

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

  • Go to the Authentication within your organization settings page.
  • In the Directory sync section, click the identity provider link to open up the directory configuration page
  • Click the Edit Attribute Map button and in the form, enter the folllowing:
    • Directory Provider Value: planetscale_role
    • PlanetScale Attribute: planetscale_role
  • Click Save mappings

Enable in PlanetScale

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

  • Go to your SSO organization's settings page
  • Click on Authentication in the side navigation
  • Check the Manage PlanetScale roles through identity provider's directory checkbox

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, or join our GitHub discussion board to see how others are using PlanetScale.

Was this page useful?
Last updated on Help us improve this page