Index
Edit

Third-Party Login (SSO)

Users that have activated custom access control on their plan may replace a project's user database with their own custom login solution, e.g. to integrate with a single sign-on (SSO) system such as Active Directory or Kerberos.

Sanity provides APIs to register users and permissions for datasets and create Sanity sessions, but it is up to the customer to actually implement the integration with their authentication system.

Implementing third-party login involves:

  • Registering Sanity groups with appropriate permissions via the API, either manually or with code.
  • Writing code to generate a Sanity session when a user logs in.
  • Optionally modifying the content studio to use a separate login form.

We'll go through each of these steps in detail below.

We also have a sample Node.js application that shows how to go about this using Passport.js. It currently has support for authenticating with Google's OAuth and Okta's SAML API.

Managing groups and users

Sanity uses groups to grant permissions to various users, as described in the access control section. You will first need to set up the groups and permissions that you need, as well as group memberships for users. Depending on your use case it may be sufficient to simply set up the groups manually, but we expect most users will require code to automatically keep groups in sync with their local database.

Gotcha

Due to Sanity implementation details, custom user IDs must begin with e. We suggest using the prefix e-.

Pro-tip

There is no need to create Sanity users corresponding to your local users, it is sufficient to simply list the user IDs as group members.

Groups are stored as regular Sanity documents of type system.group under the _.groups. path, as outlined in the access control section. Use regular mutations via the API to create and modify them.

For example, let's say we would like to give the journalists e-henrik and e-emma in our Norway office full access to all articles in the norway edition, but only read access to other editions - we could create the following group for this:

{
  _id: '_.groups.office-norway',
  _type: 'system.group',
  grants: [
    {
      filter: "_type == 'article' && edition._ref == 'norway'",
      permissions: ["create", "update", "read"]
    },
    {
      filter: "_type == 'article'",
      permissions: ["read"]
    }
  ],
  members: ["e-henrik", "e-emma"]
}
Pro-tip

Sanity user IDs may be exposed in publicly available data (e.g. as the author of a document), so take care not to use any personally identifiable information when generating IDs. An arbitrary number or a hash is usually a good choice.

Once all of our groups and memberships are properly set up, we'll need to give users a Sanity token when they log in.

Generating Sanity tokens

You will need some sort of login solution on your end, which authenticates users with your user database and then makes an API call to Sanity to generate a session claim. The details depend entirely on the specific authentication system you use, but we have a GitHub repo with a complete example.

Once you have authenticated the user you should make an HTTP POST request using a robot token that has the create-session permission to the following endpoint:

POST https://<projectId>.api.sanity.io/v1/auth/thirdParty/session

The POST body should be JSON- or URL-encoded and contain the following fields:

  • userId: the user's ID as listed in the group (see above).
  • userFullName: the user's full name.
  • userEmail: the user's email address.
  • userImage: optional HTTPS URL to the user's profile image.
  • sessionExpires: ISO timestamp for when the session should expire.
  • sessionLabel: optional label for the session.

The API call will return JSON with two fields; token and endUserClaimUrl. If the session is to be used for managing content in the content studio, the endUserClaimUrl contains a URL which the end user's browser can visit to obtain a Sanity session (set as a cookie). This URL is valid for a single use only. You can add a query parameter origin with a URL to redirect the user to after the session has been created - this URL must be listed as a valid CORS origin for the project. For other use cases, such as creating native applications, you'll want to store the token returned in a secure location and use it to authenticate requests against the Sanity API.

Using external logins in the content studio

The content studio can be configured to use your own login solution rather than the standard ones by modifying the config file config/@sanity/default-login.json in the studio code and adding e.g.:

{
  "providers": {
    "mode": "replace",
    "redirectOnSingle": true,
    "entries": [
      {
        "name": "custom-login",
        "title": "Custom Login",
        "url": "https://mydomain.com/login"
      }
    ]
  }
}

Previous: Access ControlNext: Realtime Updates