ThothII/docs/architecture/authentication.md

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, generic OIDC guide, and Authentik guide for operator procedures.