91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# Local authentication
|
||
|
||
Use local mode for a standalone PC or Mac, with `shell.mode: full` and
|
||
`shell.defaultLocale: en` in the installation descriptor. Presentation and
|
||
authentication are independent: selecting full does not create accounts. Omics
|
||
embedded instead uses the [upstream guide](shell-and-language.md), not local users.
|
||
|
||
Configure local authentication 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
|
||
|
||
Full shows its own login form and, after login, the verified display name in its
|
||
header. The name menu contains Log out. This sends a CSRF-protected request to
|
||
`/api/auth/logout`, revokes the session and returns to login. Language/theme
|
||
preferences may remain in the browser; they are not credentials.
|
||
|
||
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.
|
||
|
||
## Projected server installations
|
||
|
||
This section applies only when a Linux `profile: server` descriptor declares a runtime projection.
|
||
The canonical authentication root stays root-owned and is the only authority. The container reads
|
||
only the separate read-only runtime projection selected by `CURRENT`; it never falls back to the
|
||
canonical files or to a previous generation. Run projected mutations and repairs through the
|
||
root-operated `tht` commands, and never edit runtime files directly.
|
||
|
||
Mac, Windows, and local direct-file authentication remain unchanged when the projection is absent.
|