docs(auth): document local OIDC and Authentik operation

2026-08-18 03:07:33 +02:00
parent 6ec5b76c54
commit f4f38717e1
17 changed files with 407 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Local authentication
+
+Use local mode for a standalone PC or Mac. Configure it through `tht`; passwords are entered at an
+echo-free prompt or read from a protected `--password-file`, never from a command argument.
+
+## Bootstrap
+
+After the installation descriptor and protected secret bundle exist, configure the first enabled
+administrator:
+
+```sh
+tht --installation /absolute/path/thothii-installation.yaml auth configure \
+  --mode local --public-url http://127.0.0.1:8080 \
+  --admin-user <operator-user> --admin-display-name <display-name> \
+  --password-file /absolute/path/protected-password-file
+```
+
+The password file is temporary operator input: keep it private and remove it after configuration.
+The resulting `users.yaml` contains Argon2id hashes, never plaintext passwords. To use prompts,
+omit the admin and password options in an interactive terminal. `tht setup` performs the same
+bootstrap before it starts the stack.
+
+The non-secret local `auth.yaml` has this exact shape:
+
+~~~yaml
+version: 1
+mode: local
+publicUrl: http://127.0.0.1:8080
+session:
+  regularTtlSeconds: 43200
+  regularIdleSeconds: 7200
+  rememberTtlSeconds: 2592000
+  rememberIdleSeconds: 604800
+  oidcTtlSeconds: 28800
+local:
+  usersFile: users.yaml
+~~~
+
+## User administration
+
+```sh
+tht auth user list [--json]
+tht auth user add <username> --role user|admin [--display-name <name>] [--password-file <file>]
+tht auth user set-password <username> [--password-file <file>]
+tht auth user enable <username>
+tht auth user disable <username>
+tht auth user grant <username> --role user|admin
+tht auth user revoke <username> --role user|admin
+tht auth user logout-all <username> --yes
+```
+
+User commands are unavailable in OIDC mode. The last enabled administrator cannot be disabled or
+demoted. Every password, role, enabled-state, and `logout-all` change increments the user’s
+`authRevision`, invalidating its sessions. `tht auth status --json` is redacted and suitable for
+machine use; JSON output is pristine on stdout.
+
+## Session behavior and recovery
+
+An ordinary login expires after 2 hours idle or 12 hours absolute. Selecting **Remember me** makes
+the cookie persistent and changes the limits to 7 days idle or 30 days absolute. Remembered
+sessions survive a browser and backend restart, but not a user revision change, configuration
+revision change, logout, or restore. Restore does not include sessions or OIDC state and requires
+every user to authenticate again.
+
+If access is lost, use `tht auth user set-password`, `enable`, role changes, or `logout-all` as
+appropriate, then log in again. Do not copy passwords, hashes, cookies, CSRF values, or secret
+values into tickets, logs, or evidence.
+
+Check readiness with `tht auth check`; add `--json` for the machine contract. Use
+`tht doctor --json` for the aggregate installation report.