Single sign-on

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.

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.

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.

Creating Profile Attributes in Okta

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: string
• The Display name, Variable name, and External name should be defined as 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
• Select READ_WRITE under Mutability.

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

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.

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