# 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:
1. Setting up Multi-Factor Authentication (MFA) for admin accounts
2. Creating new API tokens after admin account changes
3. 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

1. Open browser and navigate to http://localhost:6875
2. Click "Sign In"
3. Enter credentials:
   - **Email:** john@alai.no
   - **Password:** BkStk_J0hn_2026!Secure

### Step 2: Access Account Settings

1. Click on your profile icon (top-right corner)
2. Select "Edit Profile" or "My Account"

### Step 3: Enable MFA

1. Scroll to "Multi-Factor Authentication" section
2. Click "Setup MFA"
3. Choose method:
   - **TOTP (Recommended):** Time-based One-Time Password (Google Authenticator, Authy, etc.)
   - **Backup Codes:** Generate backup recovery codes

4. 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)

5. Click "Confirm" to enable MFA

### Step 4: Test MFA

1. Log out
2. Log back in with same credentials
3. Verify you're prompted for MFA code
4. Enter code from authenticator app
5. 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

1. Login to BookStack as john@alai.no
2. Click profile icon (top-right)
3. Select "Edit Profile" or "My Account"
4. Click on "API Tokens" tab

### Step 2: Create Token

1. Click "Create Token"
2. Enter token details:
   - **Name:** System Integration Token
   - **Expiry:** Never (or set appropriate expiry)
3. 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:

```bash
# Edit the config file
nano ~/system/config/bookstack.json
```

Replace `token_id` and `token_secret` with new values:

```json
{
  "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

```bash
# 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:

1. Edit docker-compose.yml:
   ```bash
   cd ~/system/services/bookstack
   nano docker-compose.yml
   ```

2. Change:
   ```yaml
   - ALLOW_GUEST_ACCESS=true
   ```
   to:
   ```yaml
   - ALLOW_GUEST_ACCESS=false
   ```

3. Restart BookStack:
   ```bash
   docker compose restart bookstack
   ```

### Review User Permissions

1. Login as admin
2. Go to Settings (gear icon) → Users
3. Review all user accounts
4. Set appropriate roles (Admin, Editor, Viewer)
5. Remove or deactivate unused accounts

### Enable Audit Log

1. Settings → Audit Log
2. Enable logging of user actions
3. Review periodically for suspicious activity

### Regular Backups

Ensure regular backups are configured:

```bash
# 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:**
1. Check time sync on server and phone (TOTP requires accurate time)
2. Use backup codes if available
3. Reset MFA via database (emergency only):
   ```bash
   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:**
1. Delete old token in web UI (API Tokens tab)
2. Create new token (see Part 2)
3. Update config file

### Cannot Access Web UI

**Problem:** BookStack returns 500 error or won't load

**Solutions:**
1. Check container status: `docker ps | grep bookstack`
2. Check logs: `docker logs bookstack --tail 100`
3. Restart service: `cd ~/system/services/bookstack && docker compose restart`

---

## Security Best Practices

1. **MFA on all admin accounts** - Always enable MFA for admins
2. **Strong passwords** - Use 20+ character passwords with mixed case, numbers, symbols
3. **Regular token rotation** - Rotate API tokens every 90 days
4. **Least privilege** - Give users minimum permissions needed
5. **Audit logs** - Review regularly for suspicious activity
6. **Backups** - Daily database + data backups
7. **HTTPS** - Use Cloudflare tunnel for external access (see bookstack.md)
8. **Keep updated** - Update BookStack image regularly

---

## Next Steps

After completing this setup:

1. [ ] Enable MFA for john@alai.no
2. [ ] Create new API token
3. [ ] Update ~/system/config/bookstack.json
4. [ ] Test API token works
5. [ ] Enable MFA for alem@basicconsulting.no
6. [ ] Review and set user permissions
7. [ ] Configure daily backups
8. [ ] Consider Cloudflare tunnel for external access

---

**Last updated:** 2026-02-17
**Maintained by:** John (AI Director)
**Related:** ~/system/context/docs/runbooks/bookstack.md