Benutzerkonfiguration - user.toml

Wichtige Informationen zur Benutzerdatenbank

In der TOML-Datei users.toml werden die Benutzer, sowie ihre jeweiligen Passwörter, Rollen und Kartenschlüssel gespeichert. Die Datei befindet sich üblicherweise in /etc/bffh/ oder in /opt/fabinfra/bffh-data/config/ (je nach Setupmethode). Die Datei wird nicht automatisch von BFFH geladen - egal, ob sie komplett neu ist oder nur modifiziert wurde. Das Importieren der users.toml erfolgt durch bffhd --load.

BFFH selbst nutzt eine interne Datenbank (bffh.db) für die Benutzer, jedoch wird diese erstmalig über die Datei users.toml gespeist. Nachdem mindestens eine erste Verwaltungsrolle inkl. zugewiesenem Benutzer (Admin, Manager) zum System hinzugefügt wurde, kann anschließend auch die Benutzerverwaltung der Client-Anwendung Borepin genutzt werden. Über diese lassen sich Benutzer hinzufügen und entfernen, sowie Rollen und Passwörter managen. Die in der App hinzugefügten bzw. modifizierten Benutzer werden nicht automatisch in die erstmalig genutzte users.toml geschrieben. Das erfolgt explizit durch bffhd --dump-users. Für unsere Handhabe bedeutet das, dass die parallele Bearbeitung der Benutzerdatenbank per App und users.toml sorgfältig getätigt werden sollte, um etwaige Änderungen nicht ungewollt rückgängig zu machen.

Wer mit der automatisierten Erstellung einer users.toml aus externen Nutzerquellen wie zum Beispiel CSV-Dateien oder LDAP (siehe hier) arbeitet, der sollte folgenden Workflow erarbeiten:

BFFH Server herunterfahren
Aktuelle Benutzerkonfiguration per bffhd --dump-users users.toml sichern
die soeben gesicherte users.toml Datei benutzen, um die aktuellsten Änderungen an der Benutzerbasis hinzuzufügen, zu löschen oder zu ändern. Hier muss selbst entschieden werden, welche Benutzerdaten aktuell sein sollen: Die durch die App geänderten Daten, oder die aus der externen Quelle? Eine von beiden muss die andere überschreiben bzw. überlagern. Entsprechend muss das verwendete Script programmiert sein: bei Vorhandensein von Nutzern, Rollen, Passwörter, Cardkeys rückfragen, ob bei Differenzen der bestehende oder der neue Datensatz verwendet werden soll oder per Config-Parameter automatisiert durchführen.
die neue users.toml Datei laden: bffhd --load users.toml (siehe auch Nutzerdatenbank laden / hashen / prüfen)
BFFH Server starten

Aufbau einer users.toml

Der grundlegende Aufbau folgt dem oben verlinkten TOML-Standard. Jeder Nutzer wird dabei durch eine eigene Sektion angegeben (in einem Paar eckiger Klammern).

Achtung: Der Name kann unter anderem auch Leerzeichen und Sonderzeichen enthalten, sowie nahezu beliebig viele Zeichen. Folgender Username ist beispielsweise gültig:
["Ein seeeeeeeeeeeeeeeeeeeeeeeeeehr langer Nutzername mit Sond@rze!chen_ "]. Dem Administrator wird angeraten eine Nutzernamenkonvention aufzustellen, die z.B. verschiedene Sonderzeichen vermeidet, die häufig auch bei LDAP-gestützten Anwendungen Probleme bereiten. Es wird im Zweifelsfall empfohlen sich auf Klein- und Großbuchstaben, sowie Ziffern und einfache Zeichen wie .-_ zu beschränken.

Unter jedem [Benutzer] werden dann Schlüssel-Wert-Paare abgelegt. Die gültigen Schlüsselnamen lauten:

roles (Rollen)
passwd (Passwort - unverschlüssel (plaintext) oder als Argon2-Hash)
cardkey (DESFire EV2 UUID)

Etwaige weitere Schlüssel können angelegt werden, werden jedoch von bffh beim Laden verworfen.

Kommentare können mit # vorangestellt erzeugt werden. Diese werden beim Laden in die BFFH-Datenbank ebenso verworfen.

Beispielbenutzer und -rollen

Rollen werden in der bffh.dhall-Konfiguration definiert. Das Docker-compose Repository https://gitlab.com/fabinfra/fabaccess/dockercompose hat ein gutes Beispiel:

[Admin1]
roles = ["Admin"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[Admin2]
roles = ["Admin"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[ManagerA1]
roles = ["ManageA", "UseA", "ReadA", "DiscloseA"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[ManagerA2]
roles = ["ManageA", "UseA", "ReadA", "DiscloseA"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[ManagerB1]
roles = ["ManageB", "UseB", "ReadB", "DiscloseB"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[ManagerB2]
roles = ["ManageB", "UseB", "ReadB", "DiscloseB"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

[ManagerC1]
roles = ["ManageC", "UseC", "ReadC", "DiscloseC"]
passwd = "secret"
cardkey = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Manuelles Anlegen neuer Benutzer

Lasse alle neuen Nutzer ihre Passwörter verschlüsselt an den Admin übertragen, indem diese ihr Passwort als verschlüsselten Argon2 String übermitteln.

argon2 Passwort Auf der Kommandozeile erzeugen ...

... mit Ubuntu Linux

apt install argon2
PASSWORD="mypassword" && echo | argon2 $PASSWORD -i -k 4096 -p 1 -t 3 -l

... mit Windows

Eine Implementierung für Windows existiert zum Beispiel unter https://github.com/philr/argon2-windows

Wir laden das Release-Zip herunter, entpacken es und führen Argo2Opt.exe aus:

set PASSWORD="mypassword"
echo %PASSWORD% | Argon2Opt.exe %PASSWORD% -i -k 4096 -p 1 -t 3 -l 16

Wir übermitteln die kodierte Zeichenkette in die users.toml, hier im Beispiel: $argon2i$v=19$m=4096,t=3,p=1$UEFTU1dPUkQ$VMwncjCWdW+f6x8qzshLaA. Der Eintrag in der users.toml könnte so lauten:

[vmario]
roles = ["mitglied"]
passwd = "$argon2i$v=19$m=4096,t=3,p=1$UEFTU1dPUkQ$VMwncjCWdW+f6x8qzshLaA"
cardkey = "70AFE9E6B1D6352313C2D336ADC2777A"

argon2 Passwort mit Argon2 Hash Generator Tool

Settings:

Salt: einen neuen erzeugen durch Klicken auf das Zahnrad
Parallelism Factor: 1
Memory Cost: 4096
Iterations: 3
Hash Length: 16

Wir übermitteln die kodierte Zeichenkette, hier im Beispiel: $argon2i$v=19$m=4096,t=3,p=1$QkkyWERYNEdnQVBWSzhTQg$Lv2mrx+YRtoNrV1eDjhZcg

Benutzerkonfiguration in BFFH importieren

Eine einmal angelegte users.toml kann und muss in die BFFH-interne Datenbank importiert werden. Details siehe

Benutzerkonfiguration aus BFFH exportieren

Die in der BFFH-Datenbank gespeicherten Benutzer können mit dem Zusatz --dump-users in eine users.toml Datei exportiert werden:

BASE="/opt/fabinfra/bffh/target/release"
CFG="$DATA/config/bffh.dhall"
$BASE/bffhd --verbose --config $CFG --dump-users /tmp/users.toml --force

Siehe auch Cheat Sheet - Wichtigste Befehle (Übersicht)

Weitere Tipps und und Tricks mit TOML Dateien

Ein paar weitere Tools, die das digitale Leben ggf. vereinfachen.

TOML-Dateien sortieren (nach Sektionen, Arrays, etc.) mit toml-sort

https://pypi.org/project/toml-sort

pip install toml-sort

toml-sort --help
usage: toml-sort [-h] [--version] [-o OUTPUT] [-i] [-I] [-a] [--no-sort-tables] [--sort-table-keys]
                 [--sort-inline-tables] [--sort-inline-arrays] [--sort-first KEYS] [--no-header] [--no-comments]
                 [--no-header-comments] [--no-footer-comments] [--no-inline-comments] [--no-block-comments]
                 [--spaces-before-inline-comment {1,2,3,4}] [--spaces-indent-inline-array {2,4,6,8}]
                 [--trailing-comma-inline-array] [--check]
                 [F ...]

Mit folgendem Kommando lassen sich zu Beispiel users.toml Dateien sortieren und gleichzeitig überschreiben.

toml-sort --in-place --all /opt/fabinfra/bffh-data/config/users.toml

TOML-Dateien als JSON ausgeben/verarbeiten

Analog zum bekannten Werkzeug JSON-Parser jq gibt es das Tool yq auch für TOML (als Wrapper für jq): https://kislyuk.github.io/yq/#toml-support

pip install yq

Durch dieses Paket wird ebenfalls die Binary tomlq automatisch mit installiert. Bitte beachten: Das gleichnamige Paket tomlq gibt es separat auf PyPI, ist jedoch stark veraltet und inkompatibel zu neuen Python Versionen. Es wird daher empfohlen das beinhaltende, aktuellere Paket yq zu installieren.

Unsere users.toml als JSON-Objekt ausgeben:

tomlq '.' /opt/fabinfra/bffh-data/config/users.toml

Mit dem nachfolgenden Befehl überschreiben wir eine users.toml Dateien so, dass z.B. alle Kommentare entfernt werden:

tomlq -t -i '.' /opt/fabinfra/bffh-data/config/users.toml