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.

flowchart TB
    BROWSER["Browser"] --> BOUNDARY["Authentication boundary"]
    BOUNDARY --> LOCAL["Local users\nArgon2id hashes"]
    BOUNDARY --> OIDC["OIDC provider\nAuthorization Code PKCE"]
    OIDC --> GROUPS["Groups claim\nexact mapping"]
    LOCAL --> PRINCIPAL["Thoth principal"]
    GROUPS --> PRINCIPAL
    PRINCIPAL --> ROLES["Roles"]
    ROLES --> PERMISSIONS["Permissions"]
    PERMISSIONS --> ROUTES["Protected routes"]
    SECRETS["Mounted secret bundle"] -.-> BOUNDARY

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 production role expansion from backend/src/auth/config.ts is exact:

Role	Permissions
user	session.use
admin	session.use, session.read_all, session.manage_all, settings.manage, workspace.manage, workspace.secrets.manage, database.manage, memory.manage, evidence.manage, pi.manage, auth.diagnostics.read

admin therefore includes the ordinary session.use permission. No other role or permission label is part of the production catalog.

After validating a browser session, the backend expands its roles through the current permission catalog on every request. The permissions saved at login are a historical snapshot, so existing administrator sessions can use newly deployed administration features without signing in again. Session expiry, revocation and local-user role validation still apply before role expansion.

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. The browser callback returns HTTP 401 with the generic code oidc_callback_failed; it does not expose the internal reason. Authentication diagnostics and interactive device-flow validation use oidc_groups_claim_invalid for invalid group-claim/identity results. 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.

Diagnostics and ordering

The closed production diagnostic-code union is:

auth_ready
auth_config_incomplete
auth_config_invalid
auth_session_store_invalid
local_user_registry_invalid
local_admin_missing
oidc_secret_missing
oidc_discovery_unreachable
oidc_issuer_mismatch
oidc_jwks_unreachable
oidc_group_catalog_unreachable
oidc_group_catalog_unauthorized
oidc_mapped_group_missing
oidc_mapped_group_ambiguous
oidc_groups_claim_invalid
oidc_device_flow_unavailable

Workspace Validate performs static authentication validation without provider connectivity. tht auth check performs live, non-interactive diagnosis: static safety plus OIDC discovery, issuer/JWKS, group-catalog authentication, and exact configured-group existence. Adding --interactive runs that same live diagnosis and then validates a device-flow identity when the provider supports Device Authorization. Aggregate live workspace and authentication validation is available through the installation diagnostics.

The ordered tht doctor report is exactly: descriptor, files, docker, compose, configuration, authentication, services, core-http, frontend-http, workspace-registry, workflow, pi. Its authentication entry is the live non-interactive diagnosis against the healthy running core; later checks may be skipped when an earlier prerequisite fails.

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.