Use SlashID with Docusaurus

Use the @slashid/docusaurus-theme-slashid Docusaurus theme to protect the content of your Docusaurus website. Use a combination of path-based and front matter driven configuration to granularly define access rules to your content. Follow this guide to get started quickly.

Prerequisites

Before starting, sign up for a free account with SlashID to get an organization ID.

Setup

tip

We support websites generated with both Docusaurus v2 and v3 that use the @docusaurus/preset-classic.

SlashID authentication for Docusaurus is implemented as a custom theme, built on top of @docusaurus/theme-classic.

Installation

In the first step we install it using a package manager of your choice:

npm

npm install @slashid/docusaurus-theme-slashid

Yarn

yarn add @slashid/docusaurus-theme-slashid

Configuration

Having installed the package, the rest of the setup is done in docusaurus.config.js. Please follow the next steps to completion as they are all required for a succesful integration.

Adding the theme

In your docusaurus.config.js file add @slashid/docusaurus-theme-slashid to the themes field:

{
  // ...
  themes: ["@slashid/docusaurus-theme-slashid"]
}

Applying the styles

Add the CSS needed for the built in login form to the preset options:

{
    // ...
    theme: {
        customCss: [
            require.resolve("@slashid/react/style.css"),
            // don't remove any existing custom css
        ],
    }
}

Adding the Auth button

You can render a button in the navbar to allow customers to log in. To do so, add this item to the navbar.items field in the themeConfig:

{
  // ...
  themeConfig: ({
    // ...
    navbar: {
      // ...
      items: [
        // ...
        {
          type: "custom-AuthButton",
          position: "right",
          className: "button button--secondary button--lg",
        },
      ],
    },
  })
}

Configuration

Finally, add the slashID configuration object to your themeConfig options:

{
  // ...
  themeConfig: ({
    slashID: {
      orgID: "<ORGANIZATION_ID>", // your SlashID organization ID
      forceLogin: true || false, // require login regardless of other settings
      // redirect unauthenticated users to privateRedirectPath
      // alternatively set this to "modal" to display the login form instead
      uxMode: "redirect",
      privateRedirectPath: "/",
      privatePaths: [
        {
          path: "a glob or a regex specifiying the path to protect",
          groups: ["optional list of groups that can access the path"],
        },
      ],
      formConfiguration: {
        // authentication methods presented to end users
        factors: [{ method: "email_link" }],
        // logo you want to display on the login form
        logo: "<YOUR_LOGO_URL>",
        // customisable text content
        text: {
          "initial.title": "SlashID Docusaurus login theme",
        },
      },
    },
  })
}

Let's look at these options in more detail:

Name	Type	Default	Description
slashID.orgID	string	null	Your SlashID organization ID.
slashID.forceLogin	boolean	false	Render the login form in front of every path for unauthenticated users
slashID.privatePaths	PrivatePath[]	undefined	Optional set of private paths.
slashID.uxMode	redirect or modal	redirect	Either show a modal with the login form or redirect on unauthenticated access
slashID.privateRedirectPath	string	/	Defines where the redirect leads to if the redirect UX mode is selected
slashID.formConfiguration	object	undefined	Optional form configuration.

Check the next section for further explanation of the privatePaths and formConfiguration fields.

Path based authentication - slashID.privatePaths

Use this setting to define the paths to your content for which the theme will require authentication. You can define multiple paths by specifying an array of items satisfying the following interface:

interface PrivatePath {
  path: string // a glob or a regex specifiying the path to protect
  groups?: string[] // optional list of groups that can access the path
}

path field can be a RegExp or a glob pattern. Any page that has a path matching the expression you added here will require your users to be authenticated in order to render.

groups is an optional array of SlashID groups that the authenticated user must belong to in order to access the page.

Example use cases:

path	Outcome
/*	Authentication is required for all pages
/docs/category/tutorial---basics/*/	Authentication is required for all child pages of /docs/category/tutorial---basics/*/

Form configuration - slashID.formConfiguration

This configuration object is used to specify the authentication methods users can use to authenticate and also to customise the form UI. The values sent here are the same ones that can be passed to the <ConfigurationProvider>. Please check that page for more information.

Usage

Using the slashID.privatePaths configuration option you can specify coarse grained access rules. A more granular way of doing this on the page level is to set the sidebar_custom_props in the front matter of the given page. Let's look at an example:

sidebar_custom_props:
  slashid:
    auth: true
    groups:
      - member

The above configuration will require the user to be authenticated and belong to the member group to view the page. groups property is optional and if not specified, the user only needs to be authenticated to view the page.