Setting up Bookstack with Microsoft Authenticator

Bookstack w/

Authentication

In this blog, I will show how I configured BookStack as an application within Microsoft 365, enabling user authentication through Microsoft Authenticator, as well only giving access to users that belong to a specific group.

Screenshots

Previous slide

Next slide

Domain Setup

Cloudflare Configuration

Nginx Configuration

Server Prerequisites

Update PHP

				
					apt-get update

				
					apt-get -y install apt-transport-https lsb-release ca-certificates curl

06. I then downloaded the GPG signing key for the Sury PHP repository, and saved it to ‘usr/share/keyrings‘.

				
					curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg

07. Then I set up a new APT source list file for the PHP packages provided by Surý’s repository.

				
					sh -c 'echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'

				
					apt-get update

				
					apt install php8.1 php8.1-{curl,gd,ldap,mbstring,mcrypt,mysql,xml}

				
					php -v

Install MariaDB

				
					apt install default-mysql-server

Install GIT

				
					apt install git

Install Composer

				
					php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

				
					php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f88543c636f7cd84f6db9189d43a81e5503cda447da73c7e5b6') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

				
					php composer-setup.php

				
					php -r "unlink('composer-setup.php');"

				
					mv composer.phar /usr/local/bin/composer

				
					composer -V

Install Apache

				
					apt install apache2

				
					systemctl status apache2.service

Bookstack Installation

Server Setup

				
					cd /var/www/

				
					git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack

				
					cd bookstack/

				
					apt install php8.1-zip

				
					composer install --no-dev

				
					cp .env.example .env

				
					mysql -u root

				
					create database bookstack;

				
					show databases;

				
					create user bookstack@localhost identified by 'password';

				
					grant all privileges on bookstack.* to bookstack@localhost;

				
					flush privileges;

				
					ctrl+D

				
					nano .env

				
					# This file, when named as ".env" in the root of your BookStack install
# folder, is used for the core configuration of the application.
# By default this file contains the most common required options but
# a full list of options can be found in the '.env.example.complete' file.

# NOTE: If any of your values contain a space or a hash you will need to
# wrap the entire value in quotes. (eg. MAIL_FROM_NAME="BookStack Mailer")

# Application key
# Used for encryption where needed.
# Run `php artisan key:generate` to generate a valid key.
APP_KEY=base64:6E/U6eSSXbDaEiJDIgoxxxxxxxx

# Application URL
# This must be the root URL that you want to host BookStack on.
# All URLs in BookStack will be generated using this value
# to ensure URLs generated are consistent and secure.
# If you change this in the future you may need to run a command
# to update stored URLs in the database. Command example:
# php artisan bookstack:update-url https://old.example.com https://new.example.com
APP_URL=https://wiki.nestodiaz.com

# Database details
DB_HOST=localhost
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=password

				
					chown -R www-data:www-data bootstrap/cache public/uploads storage

				
					php artisan key:generate

				
					cd /etc/apache2/sites-available

				
					nano bookstack.conf

				
					<VirtualHost *:80>

	# This is a simple example of an Apache VirtualHost configuration
	# file that could be used with BookStack.
	# This assumes mod_php has been installed and is loaded.
	#
	# Change the "docs.example.com" usage in the "ServerName" directive
	# to be your web domain for BookStack.
	#
	# Change the "/var/www/bookstack/public/", used twice below, to the
	# location of the "public" folder within your BookStack installation.
	#
	# This configuration is only for HTTP, Not HTTPS.
	# For HTTPS we recommend using https://certbot.eff.org/

	ServerName https://wiki.nestodiaz.com
	DocumentRoot /var/www/bookstack/public/

	<Directory /var/www/bookstack/public/>
		Options Indexes FollowSymLinks
		AllowOverride None
		Require all granted
		<IfModule mod_rewrite.c>
			<IfModule mod_negotiation.c>
				Options -MultiViews -Indexes
			</IfModule>

			RewriteEngine On

			# Handle Authorization Header
			RewriteCond %{HTTP:Authorization} .
			RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

			# Redirect Trailing Slashes If Not A Folder...
			RewriteCond %{REQUEST_FILENAME} !-d
			RewriteCond %{REQUEST_URI} (.+)/$
			RewriteRule ^ %1 [L,R=301]

			# Handle Front Controller...
			RewriteCond %{REQUEST_FILENAME} !-d
			RewriteCond %{REQUEST_FILENAME} !-f
			RewriteRule ^ index.php [L]
		</IfModule>
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

				
					a2ensite bookstack.conf

				
					a2enmod rewrite

				
					a2enmod php8.1

				
					systemctl restart apache2

				
					cd /var/www/bookstack

				
					php artisan migrate

Accessing Bookstack

Increasing File Upload Limit

				
					cd /etc/php/8.1/apache2

				
					nano php.ini

				
					post_max_size = 100M
upload_max_filesize = 100M

SAML Setup

Entra ID

Client Secret

				
					# Set OIDC to be the authentication method
AUTH_METHOD=oidc

# Control if BookStack automatically initiates login via your OIDC system 
# if it's the only authentication method. Prevents the need for the
# user to click the "Login with x" button on the login page.
# Setting this to true enables auto-initiation.
AUTH_AUTO_INITIATE=false

# Set the display name to be shown on the login button.
# (Login with <name>)
OIDC_NAME=SSO

# Name of the claims(s) to use for the user's display name.
# Can have multiple attributes listed, separated with a '|' in which 
# case those values will be joined with a space.
# Example: OIDC_DISPLAY_NAME_CLAIMS=given_name|family_name
OIDC_DISPLAY_NAME_CLAIMS=name

# OAuth Client ID to access the identity provider
OIDC_CLIENT_ID=abc123

# OAuth Client Secret to access the identity provider
OIDC_CLIENT_SECRET=def456

# Issuer URL
# Must start with 'https://'
OIDC_ISSUER=https://instance.authsystem.example.com

# The "end session" (RP-initiated logout) URL to call during BookStack logout.
# By default this is false which disables RP-initiated logout.
# Setting to "true" will enable logout if found as supported by auto-discovery.
# Otherwise, this can be set as a specific URL endpoint.
OIDC_END_SESSION_ENDPOINT=false

# Enable auto-discovery of endpoints and token keys.
# As per the standard, expects the service to serve a 
# `<issuer>/.well-known/openid-configuration` endpoint.
OIDC_ISSUER_DISCOVER=true