Wer BookStack im Unternehmensumfeld betreibt, kennt das Problem: Benutzer anlegen, Rollen zuweisen, veraltete Accounts löschen – all das manuell über die Weboberfläche zu erledigen, kostet Zeit und ist fehleranfällig. Mit unserem Open-Source-Bash-Script bookstack-manage-users.sh lässt sich die BookStack-Benutzerverwaltung vollständig über die offizielle REST-API automatisieren.

Was das Script kann

Das Script deckt alle gängigen Verwaltungsaufgaben rund um BookStack-Benutzer und Rollen ab :

• Benutzer anlegen (user-create) aus einer CSV-Datei – inkl. automatischer Passwortgenerierung
• Benutzer aktualisieren (user-update) auf Basis von Name, E-Mail und Rollen
• Benutzer löschen (user-delete) per TXT- oder CSV-Liste
• Rollen zuweisen, entfernen oder migrieren (role-add, role-remove, role-move)
• Benutzer und Rollen exportieren (user-list, role-list) als Semikolon-CSV

Voraussetzungen

Auf dem System müssen folgende Tools vorhanden sein :

• bash, curl, jq
• python3 (für CSV-Parsing und Passwortgenerierung)
• Eine laufende BookStack-Instanz mit aktivierter API
• Ein API-Token eines Benutzers mit der Berechtigung Access System API

Installation und Konfiguration

git clone https://github.com/ADMIN-INTELLIGENCE-GmbH/Bookstack.git
cd Bookstack/user_management
chmod +x bookstack-manage-users.sh

Umgebungsvariablen setzen, bevor das Script ausgeführt wird :

export BOOKSTACK_URL="http://127.0.0.1"
export BOOKSTACK_TOKEN_ID="DEIN_TOKEN_ID"
export BOOKSTACK_TOKEN_SECRET="DEIN_TOKEN_SECRET"

Tipp: Wenn BookStack hinter einem Reverse Proxy läuft, empfiehlt es sich, das Script direkt auf dem BookStack-Server auszuführen und BOOKSTACK_URL=http://127.0.0.1 zu verwenden. So entfällt die TLS-Schicht für administrative Automatisierungen .

Praktische Anwendungsbeispiele

Benutzer aus CSV anlegen:

./bookstack-manage-users.sh user-create users.csv

Die CSV-Datei ist Semikolon-getrennt mit folgendem Format:

name;email;password;roles
Max Mustermann;max.mustermann@example.com;Start123!;"Staff,Wiki-Reader"
Erika Musterfrau;erika.musterfrau@example.com;;"Editors"

Ist das Passwort-Feld leer, generiert das Script automatisch ein sicheres Passwort .

Rollen migrieren:

./bookstack-manage-users.sh role-move "External" "Staff" users.txt

Alle Benutzer mit Rollen exportieren:

./bookstack-manage-users.sh --export user-list > alle-benutzer.csv

Dry-Run und Audit-Logging

Vor großen Änderungen – besonders bei role-move oder user-delete – sollte immer ein Dry-Run durchgeführt werden :

./bookstack-manage-users.sh --dry-run role-move "External" "Staff" users.csv

Für Compliance und Nachvollziehbarkeit lässt sich jede Aktion in eine CSV-Log-Datei schreiben:

./bookstack-manage-users.sh --log-csv audit.csv user-update users.csv

Das Log enthält Zeitstempel, Modus, Status, Benutzerdetails, Rollen vor/nach der Änderung sowie den JSON-Payload – und lässt sich direkt in Excel oder LibreOffice öffnen .

Sicherheitshinweise

• Immer mit einem dedizierten Service-Account-Token mit minimalen Rechten arbeiten
• Alle Läufe via --log-csv protokollieren
• Token-Gültigkeit und Berechtigungen werden vor jedem Lauf automatisch per Preflight-Request gegen /api/users?count=1 geprüft

Weiterführend Links

Das Open-Source-Script und der zugehörige Quellcode für die automatisierte BookStack-Benutzerverwaltung finden Sie im GitHub-Repository von ADMIN INTELLIGENCE. Ergänzende Informationen zu Installation, Hosting und Betrieb von BookStack finden Sie auf unserer Seite BookStack Hosting & Setup. Weitere Beiträge und Praxisbeispiele rund um das Thema finden Sie in unserer BookStack-Kategorie im Blog. Die Implementierung nutzt die offizielle REST-API von BookStack; die passende BookStack API-Dokumentation beschreibt die Endpunkte, die Authentifizierung und die Nutzung mit API-Tokens. Wenn Sie Unterstützung bei der Integration oder beim Betrieb benötigen, erreichen Sie uns über unser Kontaktformular.