BookStack MFA Setup

Last Verified: 2026-02-17 | Owner: John 
 
 BookStack MFA and API Token Setup 
 Service: BookStack Knowledge Base
 URL: http://localhost:6875 or http://192.168.68.61:6875 
 
 Overview 
 This runbook covers: 
 
 Setting up Multi-Factor Authentication (MFA) for admin accounts 
 Creating new API tokens after admin account changes 
 Security best practices 
 
 
 Prerequisites 
 
 BookStack is running and accessible 
 Admin account: john@alai.no (password: BkStk_J0hn_2026!Secure) 
 Browser access to BookStack web interface 
 
 
 Part 1: Enable MFA (Multi-Factor Authentication) 
 Step 1: Login as Admin 
 
 Open browser and navigate to http://localhost:6875 
 Click "Sign In" 
 Enter credentials:
 
 Email: john@alai.no 
 Password: BkStk_J0hn_2026!Secure 
 
 
 
 Step 2: Access Account Settings 
 
 Click on your profile icon (top-right corner) 
 Select "Edit Profile" or "My Account" 
 
 Step 3: Enable MFA 
 
 
 Scroll to "Multi-Factor Authentication" section 
 
 
 Click "Setup MFA" 
 
 
 Choose method: 
 
 TOTP (Recommended): Time-based One-Time Password (Google Authenticator, Authy, etc.) 
 Backup Codes: Generate backup recovery codes 
 
 
 
 For TOTP setup: 
 
 Scan QR code with authenticator app 
 Enter 6-digit verification code 
 Save backup codes in secure location (~/system/config/bookstack-mfa-backup.txt) 
 
 
 
 Click "Confirm" to enable MFA 
 
 
 Step 4: Test MFA 
 
 Log out 
 Log back in with same credentials 
 Verify you're prompted for MFA code 
 Enter code from authenticator app 
 Successful login confirms MFA is working 
 
 
 Part 2: Create New API Token 
 The old API token was invalidated when the default admin@admin.com account was deleted.
You need to create a new token for the john@alai.no account. 
 Step 1: Navigate to API Settings 
 
 Login to BookStack as john@alai.no 
 Click profile icon (top-right) 
 Select "Edit Profile" or "My Account" 
 Click on "API Tokens" tab 
 
 Step 2: Create Token 
 
 Click "Create Token" 
 Enter token details:
 
 Name: System Integration Token 
 Expiry: Never (or set appropriate expiry) 
 
 
 Click "Save" 
 
 Step 3: Copy Token Credentials 
 IMPORTANT: Token secret is only shown once! 
 You will see: 
 
 Token ID: (example: jpipe2-abc123xyz) 
 Token Secret: (long hexadecimal string) 
 
 Copy both values immediately. 
 Step 4: Update Config File 
 Update ~/system/config/bookstack.json with new token: 
 # Edit the config file
nano ~/system/config/bookstack.json
 
 Replace token_id and token_secret with new values: 
 {
 "url": "http://localhost:6875",
 "external_url": "http://192.168.68.61:6875",
 "token_id": "YOUR_NEW_TOKEN_ID",
 "token_secret": "YOUR_NEW_TOKEN_SECRET",
 "admin_email": "john@alai.no",
 "admin_password": "BkStk_J0hn_2026!Secure",
 "alem_email": "alem@basicconsulting.no",
 "alem_password": "V4YawdA13PdsRBIOtFz9"
}
 
 Save the file (Ctrl+O, Enter, Ctrl+X in nano). 
 Step 5: Test API Token 
 # Read token from config
TOKEN_ID=$(cat ~/system/config/bookstack.json | grep token_id | cut -d'"' -f4)
TOKEN_SECRET=$(cat ~/system/config/bookstack.json | grep token_secret | cut -d'"' -f4)

# Test API call
curl -s -H "Authorization: Token $TOKEN_ID:$TOKEN_SECRET" http://localhost:6875/api/shelves
 
 Expected: JSON response with list of shelves. 
 If you see {"error":{"message":"No matching API token was found"...}} , the token is incorrect. 
 
 Part 3: Additional Security Measures 
 Disable Guest Access (Optional) 
 If you want to require authentication for all access: 
 
 
 Edit docker-compose.yml: 
 cd ~/system/services/bookstack
nano docker-compose.yml
 
 
 
 Change: 
 - ALLOW_GUEST_ACCESS=true
 
 to: 
 - ALLOW_GUEST_ACCESS=false
 
 
 
 Restart BookStack: 
 docker compose restart bookstack
 
 
 
 Review User Permissions 
 
 Login as admin 
 Go to Settings (gear icon) → Users 
 Review all user accounts 
 Set appropriate roles (Admin, Editor, Viewer) 
 Remove or deactivate unused accounts 
 
 Enable Audit Log 
 
 Settings → Audit Log 
 Enable logging of user actions 
 Review periodically for suspicious activity 
 
 Regular Backups 
 Ensure regular backups are configured: 
 # Database backup
docker exec bookstack_db mysqldump -u bookstack -p8CdydCxVBD7wBoCVRXZE bookstackapp | gzip > ~/backups/bookstack-$(date +%Y%m%d).sql.gz

# Data backup
cd ~/system/services/bookstack
tar -czf ~/backups/bookstack-data-$(date +%Y%m%d).tar.gz data/
 
 Add to daily cron job or LaunchAgent. 
 
 Troubleshooting 
 MFA Not Working 
 Problem: Can't login with MFA code 
 Solutions: 
 
 Check time sync on server and phone (TOTP requires accurate time) 
 Use backup codes if available 
 Reset MFA via database (emergency only):
 docker exec bookstack_db mysql -u bookstack -p8CdydCxVBD7wBoCVRXZE bookstackapp \
 -e "UPDATE users SET mfa_values = NULL WHERE email = 'john@alai.no';"
 
 
 
 Lost API Token 
 Problem: Token was not saved and is no longer visible 
 Solution: 
 
 Delete old token in web UI (API Tokens tab) 
 Create new token (see Part 2) 
 Update config file 
 
 Cannot Access Web UI 
 Problem: BookStack returns 500 error or won't load 
 Solutions: 
 
 Check container status: docker ps | grep bookstack 
 Check logs: docker logs bookstack --tail 100 
 Restart service: cd ~/system/services/bookstack && docker compose restart 
 
 
 Security Best Practices 
 
 MFA on all admin accounts - Always enable MFA for admins 
 Strong passwords - Use 20+ character passwords with mixed case, numbers, symbols 
 Regular token rotation - Rotate API tokens every 90 days 
 Least privilege - Give users minimum permissions needed 
 Audit logs - Review regularly for suspicious activity 
 Backups - Daily database + data backups 
 HTTPS - Use Cloudflare tunnel for external access (see bookstack.md) 
 Keep updated - Update BookStack image regularly 
 
 
 Next Steps 
 After completing this setup: 
 
 Enable MFA for john@alai.no 
 Create new API token 
 Update ~/system/config/bookstack.json 
 Test API token works 
 Enable MFA for alem@basicconsulting.no 
 Review and set user permissions 
 Configure daily backups 
 Consider Cloudflare tunnel for external access 
 
 
 Last updated: 2026-02-17
 Maintained by: John (AI Director)
 Related: ~/system/context/docs/runbooks/bookstack.md