Set up SSO authentication with SAML and Azure/Entra ID

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

To navigate to the service provider configuration inside Sanity Manage:

1. In the organization you intend to add SSO to, go to Settings → SAML SSO.
2. If no SAML SSO provider exists, click Open SAML SSO configuration and proceed to create and configure a SAML SSO provider.

To navigate to the identity provider configuration in Azure:

1. Log into Azure.
2. Go to Azure Active Directory.
3. On the sidebar, go to Enterprise applications.

In Enterprise applications:

1. Select an existing SAML application or create a new enterprise application.
   If you create a new application, you can also integrate any other applications not available in the gallery.
2. Go to Set up single sign on, and then choose the SAML sign-on method to use.

If you're keeping two browser tabs or windows open side by side, now you should have one on the configuration screen inside Sanity Manage, and the other on the configuration screen in Azure.

1. In Azure, edit the Basic SAML Configuration form.
2. Add an Identifier (Entity ID) to the basic SAML configuration.
   1. Identifier (Entity ID) -> Sanity entity ID in Sanity Manage.
3. Add a Reply URL (Assertion Consumer Service URL).
   1. Reply URL (Assertion Consumer Service URL) -> Sanity callback URL in Sanity Manage.
4. Click Save.

1. In Azure, edit the Attributes & Claims form.
2. Edit the Unique User Identifier (Name ID) claim, and change the Name identifier format to Persistent.
3. Click Save.

Now, configure Azure to send the claims that Sanity requires in the expected form.
The claims (attributes) that Sanity expects are listed inside Sanity Manage:

For each claim:

1. Ensure the claim Name matches the attribute name in the table above.
2. Ensure the Namespace is deleted.
3. Ensure the Name format is set to Unspecified.
4. Ensure the Source attribute is mapped correctly. This varies, and it depends on the specific Azure Active Directory configuration.

Once all claims have been added:

Sanity requires user.firstName and user.surname. The mapping in the example replaces both fields with user.displayname.

Enterprise customers can map user identity provider roles to service provider roles. For example, users with an Azure example-azure-user-role role are mapped to the Sanity viewer role when they log in.

• To support the mapping functionality, you must configure the identity provider to send the groups of the user.
• To do so, Sanity Manage expects a groups claim with the format set to unspecified.

In Azure, add a new group claim:

Select the groups that you want Azure to send to Sanity, and assign the group claim a descriptive name:

Once you're done, save the changes.

In Azure, browse to the Set up {application name} block:

Get the Azure URLs for login and authentication, and add them to the Your Identity Provider details configuration section inside Sanity Manage:

In this scenario:

1. Azure Login URL maps to Sanity Identity Provider Single Sign-On URL.
2. Azure Azure AD Identifier maps to Sanity Identity Provider issuer.

In the SAML specification, InResponseTo is defined as

The ID of a SAML protocol message in response to which an attesting entity can present the assertion.

This setting is identity provider-specific. Azure doesn’t support it. Therefore, ensure that Enable InResponseTo is deselected/disabled.

The Signed SAML Assertion option notifies the Sanity instance that the identity provider is configured to use the signing certificate found in the Sanity service provider details section.

This is an optional step configured in Verification certificates:

Unless you have already uploaded the certificate, leave the Want assertion signed deselected under Signed SAML Assertion.

To get an X.509 certificate:

1. Go to SAML Certificates and click Edit.
2. Download the certificate as PEM certificate download.
3. Open the downloaded certificate file with any text editor, and copy-paste the certificate content into Sanity Manage.

Ensure you save all changes inside Sanity Manage and in Azure.

• Receiving a 422 error: {"statusCode":422,"error":"Unprocessable Entity","message":"child \"attributes\" fails because [\"value\" must contain at least one of ...
  • There is an issue with your claims. All claims are case sensitive and are required. Make sure the type is set to unspecified and that the namespace URI is empty and the name format is 'unspecified'
• My users are being assigned the default role and not their group mapped role
  • Ensure your mappings in Sanity are going off the Group ID within Azure/Entra ID as the ID is sent, not the name.
• When I access Sanity from my IdP dashboard, I receive:
  { "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" }
  • It does not appear you have set up your default relay state within your IdP, you will need to also configure within your Idp settings. You can follow our guide on setting the default relay state.

• Setting up Single Sign-On with SAML
• Third-Party Login (SSO)

Sanity Composable Content Cloud is the headless CMS that gives you (and your team) a content backend to drive websites and applications with modern tooling. It offers a real-time editing environment for content creators that’s easy to configure but designed to be customized with JavaScript and React when needed. With the hosted document store, you query content freely and easily integrate with any framework or data source to distribute and enrich content.

Sanity scales from weekend projects to enterprise needs and is used by companies like Puma, AT&T, Burger King, Tata, and Figma.