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.
SSO is available as an add-on for our Scaler and Scaler Pro plans and included in our Enterprise plans.
PlanetScale uses SAML SSO. Contact us to enable SSO for your organization.
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.
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.
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.
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.
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.
If you are using Okta for Single Sign-On or Directory Sync, you will need to create a new attribute for the PlanetScale application in Okta's Profile Editor.
- Data type:
- The Display name, Variable name, and External name should be defined as
- The External namespace should be defined as
- Check the box to define an enumerated list of values, add the following:
- Display name:
- Display name:
- Display name:
This attribute then needs to be mapped to the PlanetScale application in Okta.
- Open the PlanetScale application in Okta Admin Console, then select Provisioning
- Scroll down to the bottom of the
Okta to Appprovisioning page, and click
Show unmapped attributes.
planetscale_roleand click the 🖋️ to map the attribute.
Map from Okta Profileas the type and
planetscale_roleas the string.
- Save with Create & Update permission.
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.
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".