Join us and panelists from Shopify, Figma, Loom, and Fnatic for the next Sanity.io Open House. Dec 8th.

Setting up Single Sign-On with SAML

This article will take you through the process of setting up SAML (Security Assertion Markup Language) SSO (Single Sign-on) for your organization.

Summary

SAML SSO enables your organization to control access to Sanity projects by using a third-party identity provider, such as Okta or Google. When you enable SAML (Security Assertion Markup Language) SSO (Single Sign-on), users who log into a project studio or the management interface will need to sign up and create an account using the SAML SSO flow, which redirects them through the identity provider before creating an account. Once they log in, they will be assigned a default role as defined in the organization's identity and security settings.

Prerequisites

1. Set a slug for your organization

Access your organization's settings by going to sanity.io/manage and select the appropriate organization in the dropdown menu in the upper left corner. Under General Settings, you'll be able to define a unique slug that will serve to identify your organization in certain SSO workflows, such as logging in via CLI or logging into the project management console.

Your organization slug must:

  • Be globally unique
  • Be between 1-20 characters long
  • Start with an alphanumeric character
  • Contain no other characters than a-z, 0-9 and -

2. Add a SAML provider to your organization

With your organization slug set, move on to the SAML SSO settings found in the left sidebar menu. Once there, click the button aptly labeled "Create" to start setting up a new provider. This will generate the necessary details you need to connect your identity provider with your organization on Sanity.io.

Gotcha

Make sure you have at least one active project on either enterprise or business plan in your organization, or this menu item will be unavailable!

3. Use the details presented to configure the external identity provider

The process of configuring SAML SSO starts with Sanity providing you with the necessary details for setting up your external identity provider. You can use the copy button to put the correct strings on the clipboard. It's also possible to inspect the SAML XML file.

Map the values marked in blue to the corresponding fields in the next section

Be aware that different providers may use different terminology. Shown here is the interface for entering these details if you're using Okta.com. Note that “callback URL” is called “Single sign on URL.”

The values marked in blue correspond to the fields in the previous section

Note the mapping of attributes for user accounts. Sanity requires email, firstName, and lastName to be mapped to corresponding values from the identity provider. id and displayName are optional.

Gotcha

Make sure to set what groups in the external identity provider have access to the integration.

4. Configure the SAML service provider with the settings of the external identity provider

Having set up the external identity provider with the parameters you obtained from Sanity, it is now time to do the reverse. In your Sanity settings, click the button labeled Configure. You should be presented with the following dialog. Go ahead and fill in the appropriate values.

Protip

Many providers will let you download the required settings as an XML file. If you have such a file, click on the top right button labeled Upload new metadata to save yourself some tedious copy/pastes.

5. Enable SSO and set the default role for the desired project(s)

After saving your settings, you will probably want to enable SSO for one or several of your projects. In the process, you'll also set a default role for new accounts created through this identity provider. The default role can be changed at any point at your convenience.

6. Test your configuration by attempting to login

Before setting up your studio to use the new SSO setting, make sure everything is working as expected by visiting the link provided and log in to your project management console. Copy-paste the Sanity manage login URL into your browser's address bar. If correctly set up, this will log you out of your current account and into the user account given to you by your SSO identity provider. It might be convenient to test this in another browser.

7. Configure the studio to use the new SSO provider

Next, you'll want to update your studio to show the login screen from your SSO identity provider. In your studio project, locate the file config/@sanity/default-login.json and edit it to match the code provided. You have to restart your studio after saving your edits to see the new login screen.

Protip

If you'd like to keep the default login methods in addition to your new SAML SSO on your login screen, change "replace" to "append" on line 3!

8. Verify by logging in with SSO

Finally, verify that the configuration work as expected by logging in as a user from your identity provider. Your login screen should list only the appropriate options.

After logging in at least once with SAML SSO, you may want to check your organization's members in the management interface. You'll see a visual indicator on each member's avatar indicating what sign-in-method they use, allowing you to quickly make any adjustments – such as deleting or demoting accounts outside your identity provider domain.

Gotcha

SAML SSO members will take up an additional seat towards your quota since they are considered individual users in Sanity. Checking your member list for duplicates is recommended after changing your identity provider.

Was this article helpful?