Set up SSO authentication with SAML and JumpCloud

Implement single sign-on for Sanity with JumpCloud

Use this guide alongside the general SAML setup guide to configure single sign-on (SSO) for your Sanity organization using the SAML protocol, with JumpCloud as the identity provider (IdP).

During the setup and configuration process, it's a good idea to keep two windows or tabs open side by side:

• One with Sanity Manage.
• The other with the configuration settings of your IdP, JumpCloud.

• An organization with a project on the Enterprise plan.
• The Administrator role on your Sanity organization.
• Access to the JumpCloud admin portal with permission to create applications.

Go to Sanity Manage and select the organization where you want to enable SSO.

To navigate to the service provider configuration inside Sanity Manage:

• In the organization you intend to add SSO to, select Settings › SAML SSO in the sidebar.
• If no SAML SSO provider exists, click Configure and proceed to create and configure a SAML SSO provider.
• Optional: Click Download as XML to download Sanity's service provider details. You can upload this file to JumpCloud instead of copying each value by hand.
• In Your Identity Provider details, clear Enable InResponseTo. Identity-provider-initiated logins, such as opening Sanity from JumpCloud, never return InResponseTo.
• Optional: Select Enable auto update roles on login to re-apply your role mapping rules each time a user logs in with SAML SSO. While it's enabled, you can't change a SAML SSO user's roles manually in a project that has role mapping. Change the user's groups in JumpCloud instead.

• Visit https://console.jumpcloud.com/#/applications.
• Click Add New Application.
• Select Custom Application, and then click Next.

Select the following options:

• Manage Single Sign-On (SSO): Select this option, and then select Configure SSO with SAML.
• Export users to this app (Identity Management): You will want this checked if you plan on mapping roles from Sanity.

The app now appears in your list of configured applications in JumpCloud, where you continue configuring it.

In the JumpCloud admin portal, select the app and go to the SSO tab. If you downloaded Sanity's service provider details as XML, upload the file here.

Sanity requires the email, firstName, and lastName attributes. The id and displayName attributes are optional. Enter each name in Service Provider Attribute Name and choose the matching value in JumpCloud Attribute Name. Each required attribute accepts camelCase or PascalCase (email or Email), but don't send both casings of the same attribute. The assertion must also include either a NameID or an id attribute.

Set the Default RelayState option in JumpCloud so that logins route correctly to your studio or project in Sanity. If you leave it blank, you may see unexpected behavior with role mapping and with where you land after logging in. For the steps, see Setting up a default Relay State for IdP-initiated SAML logins.

With JumpCloud configured, finish the setup in Sanity Manage.

Sanity requires the Identity Provider Single Sign-On URL and the Identity Provider issuer. For JumpCloud, both take the IdP URL from your JumpCloud app.

Copy these values from JumpCloud to the fields in Sanity Manage.

To manage roles through JumpCloud user groups, set up role mapping in your Sanity SAML SSO settings. For the steps, see Enable SSO and configure role mapping for the desired projects.

Add a SAML SSO login option to your studio so that users can log in with JumpCloud. Without it, the studio's login screen doesn't offer JumpCloud. In your Sanity SAML SSO settings, expand SAML SSO login for Sanity Studio, copy the code snippet, and add it to your studio configuration file (sanity.config.ts).

After you add the snippet and deploy your studio, test the login with a JumpCloud user.

These errors are specific to JumpCloud. For SSO problems that aren't provider-specific, such as SSO not appearing as a login option in the studio, see the troubleshooting section of Setting up single sign-on with SAML.

• Receiving a 422 error: {"statusCode":422,"error":"Unprocessable Entity","message":"child \"attributes\" fails because [\"value\" must contain at least one of ...
  • The assertion is missing a required attribute, or sends it with an unsupported casing. Confirm that email, firstName, and lastName are all mapped in camelCase or PascalCase, that only one casing of each is sent, and that the assertion includes either a NameID or an id attribute.
• Groups are not being role mapped properly
  • Make sure JumpCloud sends the user's groups in an attribute named groups: in the app's SSO settings, select Include Group Attribute. The attribute name must be lowercase: Groups isn't recognized.
• Opening Sanity from your IdP dashboard shows a JSON user object instead of Sanity Manage or your studio: { "id": "3431pXO", "displayName": "Sanity Support", "email": "sanity@sanity.io", "familyName": "Sanity Support", "givenName": "Sanity", "middleName": null, "imageUrl": null, "provider": "saml-f6a94", "tosAcceptedAt": "2024-11-20T18:51:57.264Z", "createdAt": "2024-11-20T18:51:57.264Z", "updatedAt": "2024-11-20T18:51:57.535Z", "isCurrentUser": true, "providerId": "49jc94jf949930304jkojfciojlj934003490943" }
  • JumpCloud has no default relay state, so the identity-provider-initiated login stops at an API response. Set the Default RelayState option in your JumpCloud app by following the guide on setting the default relay state.

With JumpCloud SSO working, these guides cover common follow-up tasks:

• To refine which JumpCloud groups map to which Sanity roles, see Setting up single sign-on with SAML.
• Removing a user from JumpCloud doesn't remove them from your Sanity organization or projects. To find and remove former users, see Reconcile users against internal systems.