56 lines
3.2 KiB
Markdown
56 lines
3.2 KiB
Markdown
# Authentication architecture
|
|
|
|
ThothII has two production authentication modes: `local` and generic `oidc`. The host operator
|
|
surface is one CLI, `tht`; there is no separate authentication executable. The backend owns
|
|
opaque browser sessions and authorization, while `tht` owns protected configuration and local-user
|
|
files.
|
|
|
|
## Configuration and trust boundaries
|
|
|
|
The installation descriptor points to an operator-controlled authentication directory. It contains
|
|
non-secret `auth.yaml` and, for local mode, `users.yaml`. POSIX installations use a private
|
|
directory and owner-only regular files; Windows uses equivalent owner-only ACLs. Secret values are
|
|
read from the mounted secret bundle and are never placed in YAML, command arguments, logs, JSON
|
|
diagnostics, or browser storage.
|
|
|
|
Local users have Argon2id password hashes, stable IDs, enabled state, roles, and `authRevision`.
|
|
The stable roles are `user` and `admin`; `admin` inherits `user` and adds installation, session,
|
|
Pi, workspace, secret-management, and diagnostic permissions.
|
|
|
|
OIDC is provider-neutral at the browser protocol boundary. Authorization Code + PKCE, issuer,
|
|
signature, audience, expiry, state, and nonce are validated before a principal is created.
|
|
Authentik is the first certified group-catalog adapter, not a special browser login mode.
|
|
|
|
## Group authorization
|
|
|
|
OIDC must return a direct, non-empty `groups` claim whose value is a JSON array of strings.
|
|
Missing, malformed, indirect, or overage-style claims fail closed with
|
|
`oidc_groups_claim_invalid`. Exact configured external group names map to Thoth roles and then to
|
|
permissions. A user with no mapped group is authenticated but receives no role and gets `403` from
|
|
protected routes. Unmapped upstream groups are ignored silently, without an error or warning.
|
|
|
|
Every configured mapping is checked by the configured group-catalog adapter. Authentik checks the
|
|
exact group name and reports `oidc_mapped_group_missing` when it cannot find it. The dedicated
|
|
Authentik API service account has group-view-only privilege; it is separate from the OIDC client.
|
|
|
|
## Browser sessions
|
|
|
|
The browser receives only an opaque `HttpOnly`, `SameSite=Lax` cookie named `thothii_session`.
|
|
State-changing cookie requests require the in-memory CSRF token, same-origin `Origin`, and Fetch
|
|
Metadata checks when present. The frontend never stores bearer tokens or session secrets in Web
|
|
Storage.
|
|
|
|
- Ordinary local sessions: 2-hour idle and 12-hour absolute expiry; closing the browser removes
|
|
the non-persistent cookie.
|
|
- **Remember me** local sessions: 7-day idle and 30-day absolute expiry; they survive browser and
|
|
ThothII restarts.
|
|
- OIDC sessions: at most 8 hours and never beyond the validated ID-token expiry.
|
|
|
|
Local password, role, enabled-state, and logout-all changes increment `authRevision` and invalidate
|
|
affected sessions. Authentication configuration revision changes invalidate all sessions after
|
|
reload. Logout deletes the server record. Backup restore excludes active sessions and OIDC state,
|
|
recreates empty private auth-state directories, and therefore forces reauthentication.
|
|
|
|
See the [local guide](../install/authentication-local.md), [generic OIDC guide](../install/authentication-oidc.md),
|
|
and [Authentik guide](../install/authentik.md) for operator procedures.
|