Migrating Bookstack Users To Authentik
Overview
Migrating to a new Identity Provider (IDP) has it’s perks but also challenges in an existing setup. One of those was with Bookstack. If accounts already exist, an External ID is required to map the Bookstack accounts with the IDP. In this case, I’m using Authentik.
Authentik
Log in as admin and go to Applications > Providers.
Create a new provider, select OAuth/OpenID Provider
Enter the following information and leave the rest as default:
- Name: [Give it a name]
- Authentication Flow: default-provider-authorization-explicit-consent (Authorize Application)
- Client Type: Confidential
- Redirect URI: Add an entry as strict https://[bookstack]/oidc/callback. Replace [bookstack] with your URL to Bookstack.
Make a note of the Client ID and Client Secret which will be required when setting up Bookstack.
Create a new application so it will generate an issuer URL. Go to Applications > Applications and hit create button.
Give it a name and a slug. The slug is used in the URL so feel free to change this if you want to obfuscate the URL.
Select the Bookstack provider created above as the provider.
Go back to the Bookstack provider: Applications > Providers > Bookstack (replace with the name you gave your provider). Do not edit the provider, just click on the name.
Make a note of OpenID Configuration Issuer.
Now go to preview tab of the provider. Select the user from the Preview for user dropdown. Copy the value for sub which is the external ID needed to associate the user in Authentik to Bookstack. Repeat this step per user.
Bookstack
Log in as admin. This is important because once you enable OIDC using the documentation in Bookstack, it disables username and password log in. Make sure you have an admin account in Authentik setup as well if it’s separate from your day to day account.
Edit the .env file in the configuration folder. In docker, you should have a config volume mounted where this file exists in the www directory.
Copy and paste the configuration from the Bookstack documentation up to and including line OIDC_ISSUER_DISCOVER=true
# 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
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
# `
OIDC_ISSUER_DISCOVER=true
Replace the following with the Authentik values and leave the rest as default:
- OIDC_CLIENT_ID: with Client ID from Authentik Provider. E.g. yj0K3Z0td5sa84LdhHa7lWM0Kk5RZpxkB3OA2XFE
- OIDC_CLIENT_SECRET: with Client secret from Authentik Provider. E.g. I2Pz53YrjnZgnlMlEKnkacqjTlGXi0M9pF8pFH9dzIgYZk1jtJMxarjF0TQLbsMHfCXvZOW6NuGNsaOmZ2a9JwPvEtgfgIUVXiQP5hFcSlzAVTeiYKUox9hDLf38UvHB
- OIDC_ISSUER: Enter the URL from OpenID Configuration Issuer
OIDC_NAME is optional if you want to change the name of the button to log in.
Using the logged in admin account, go to Settings > Features & Security > Users.
For each user you want to associate with an Authentik account:
Click on the user name to edit the user, expand External Authentication ID to reveal a textbox.
Get the sub value using the preview for user step in Authentik, copy and paste it into External Authentication ID field.
Save the changes and repeat for each user.
Summary
The tools available along with Bookstack’s admin features make this really easy for small setups. For larger ones, a way to batch update / map accounts would be a great iteration to the feature set.
Integrating BookStack and Authentik via OpenID Connect
