Microsoft Entra ID SSO for Bookstack

ThisPrerequisites: guide shows how to integrate BookStack with Microsoft Entra ID.

Note If BookStack is used as a larger enterprise documentation platform, evaluate whether generic OIDC or SAML is the better long-term choice. The built-in AzureAD social login is simple, but not always the most flexible option.

When this approach fits

Use this guide if:

you want simple Microsoft-based sign-in BookStack is a smaller or mid-sized internal platform advanced group sync is not a hard requirement

Prerequisites

BookStack is deployed and reachable via HTTPS you can edit the .env file or container environment variables permissionAbility to create an app registration with delegated rights and access to the Bookstack Docker volume or startup method. Bookstack should be installed correctly.

Bookstack offers an OpenID interface, which means that Microsoft Entra ID can easily be used as an identity provider for managing access and permission within Bookstack. The functionalities are more limited than other integrations. However, simple functionalities such as automatic user creation and email verification can be customized.
This guide is a compilation of the main documentation of Bookstack: Third Party Authentication · BookStack (bookstackapp.com)

Create App Registration

First, an app registration including client secret must be created in Microsoft Entra ID

ID. All

Stepsettings 1:can Createbe left at the appdefault registration

values.

RecommendedImportant settings:settings are the Redirect URIs under the Authentication tab. Set these URIs to your external or internal domain on which Bookstack is available. These URIs will be used for Microsoft Entra ID to know where to redirect the user in case of successful logins.

• Platform:Authentication Type:  Web
  
• Redirect URI:URIs: https://<bookstack-domain>/bookstack.yourdomain.com/login/service/azure/callback

Record

Add the Applicationcorresponding permissions for OpenID Connect as delegated permissions and grant admin consent for your tenant.

Permissions: Delegated User permission (User.Read)

Create a client secret for the application and save the tenant ID, application ID and client secret in your password manager. You can find instructions for this information here: Get app details and grant permissions to app registration

Setup Microsoft Entra ID login provider

With Bookstack, the Microsoft Entra ID configurations can be set up using environment variables. Installation using Docker is mandatory for these instructions. The following environment variables enable the configuration of the OpenID integration.

The relevant environment variables for OpenID are as follows:

AZURE_AUTO_REGISTER: If this setting is activated, user objects are automatically created when they authenticate for the first time via Microsoft Entra ID and the user does not yet exist in Bookstack. AZURE_AUTO_CONFIRM_EMAIL: If activated this will skip the “Confirm email” setting as all email addresses are considered verified by Microsoft Entra ID. AZURE_TENANT: Here you have to enter the Tenant ID andof your Microsoft Entra ID Tenant. AZURE_APP_ID: This is the client id of your App Registration in Microsoft Entra ID. AZURE_APP_SECRET: Here you have to provide the Client Secret.Secret

Stepfrom 2:the APIApp permissions

Registration.

ForSide note: As this logintype model,of User.Readconfiguration involves environment variables, these contents can also be transferred via the volume as an .env file, specified with a simple startup command or specified in another declarative context (Kubernetes manifest, Terraform, etc.).

Docker compose example

This Docker Compose file shows a possible configuration for Bookstack that authenticates using Microsoft Entra ID. In addition, the database container and mail settings are also specified.

Customize this content with your specifications and save the content in a normal docker-compose.yaml file. As this is typicallyDocker sufficient.

Compose,

Stepthe 3:application Configurecan BookStack

be

Addstarted theseeasily variableswith tothe yourfollowing BookStackcommand .env(in ordetach containermode configuration:-> -d):

docker compose up -d

version: "3"
services:
  <yourbookstackcontainername>:
    image: lscr.io/linuxserver/bookstack
    container_name: <yourbookstackcontainername>
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://<yourbookstackdomain>
      - DB_HOST=<yourmariadbcontainername>
      - DB_USER=<yourdbuser>
      - DB_PASS=<yourdbpassword>
      - DB_DATABASE=<yourdbname>
      - MAIL_HOST=<yourmailserver>
      - MAIL_PORT=587
      - MAIL_FROM_NAME=<yourmailname>
      - MAIL_FROM=<yoursmtpmail>
      - MAIL_USERNAME=<yoursmtpmailuser>
      - MAIL_PASSWORD=<yoursmtpmailpassword>
      - AZURE_APP_ID=<client-idyourclientid>
      - AZURE_APP_SECRET=<client-secretyourclientsecret>
      - AZURE_TENANT=<tenant-idyourtenantid>
      - AZURE_AUTO_REGISTER=true
      - AZURE_AUTO_CONFIRM_EMAIL=true
    volumes:
      - <yourpersistentpathforbookstack>:/config
    ports:
      - 6875:80
    restart: unless-stopped
    depends_on:
      - <yourmariadbcontainername>
  <yourmariadbcontainername>:
    image: lscr.io/linuxserver/mariadb
    container_name: <yourmariadbcontainername>
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=<yourdbrootpassword>
      - TZ=<yourtimezone>
      - MYSQL_DATABASE=<yourdbname>
      - MYSQL_USER=<yourdbuser>
      - MYSQL_PASSWORD=<yourdbpassword>
    volumes:
      - <yourpersistentpathformariadb>:/config
    restart: unless-stopped

Best practices

use HTTPS only keep the app registration dedicated to BookStack use auto-registration only if onboarding should be self-service consider OIDC or SAML if role and group mapping becomes important

Summary

The built-in Azure/Microsoft login in BookStack is a clean solution for simple internal SSO. For more advanced enterprise access models, evaluate OIDC or SAML.