ThothII/docs/install/authentication-oidc.md

Generic OIDC authentication

OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code, PKCE S256, state, nonce, issuer/signature/audience/expiry validation, and the fixed callback <publicUrl>/api/auth/oidc/callback. The browser and API must use the same origin; configure the reverse proxy to preserve that public origin and callback path.

Configure the installation with tht:

tht auth configure --mode oidc --public-url <https-public-origin> \
  --issuer <https-issuer> --client-id <client-id> \
  --authentik-base-url <https-provider-origin> \
  --user-group 'TOT Users' --admin-group 'TOT Admin'

The OIDC client secret is supplied through the protected secret bundle under the exact key THT_OIDC_CLIENT_SECRET; it is never written into auth.yaml. The default scopes are exactly openid, profile, and email.

The non-secret OIDC configuration has this exact shape (replace angle-bracket placeholders with operator values):

version: 1
mode: oidc
publicUrl: <https-public-origin>
session:
  regularTtlSeconds: 43200
  regularIdleSeconds: 7200
  rememberTtlSeconds: 2592000
  rememberIdleSeconds: 604800
  oidcTtlSeconds: 28800
oidc:
  issuer: <https-issuer>
  clientId: <client-id>
  clientSecretRef: THT_OIDC_CLIENT_SECRET
  scopes: [openid, profile, email]
  groupsClaim: groups
groupCatalog:
  driver: authentik
  baseUrl: <https-provider-origin>
  apiTokenRef: THT_AUTHENTIK_API_TOKEN
authorization:
  groupRoles:
    TOT Users: [user]
    TOT Admin: [admin]

The groups claim is mandatory

The ID token must contain a direct, non-empty groups array of strings. ThothII does not follow distributed claims, overage links, or indirect provider expansion. Missing or malformed claims fail closed. A browser callback exposes only HTTP 401 oidc_callback_failed; it never reveals whether the claim was missing, malformed, indirect, or overage-style. The redacted diagnostic and interactive device-flow contract uses oidc_groups_claim_invalid for invalid group-claim or device-flow identity results.

Configured group names are exact and case-sensitive. The union of matched mappings determines the Thoth roles. A token with no mapped group is authenticated but has no role and cannot use protected routes. Additional provider groups are ignored silently, without an error or warning. Group existence is separately proven by the configured catalog adapter; this is why a generic OIDC provider may authenticate while still failing installation readiness.

Checks and diagnostics

The surfaces have distinct semantics and this order is recommended:

1. Workspace Validate performs static authentication validation without contacting the provider.
2. tht auth check performs live, non-interactive authentication diagnosis, including discovery, issuer/JWKS, catalog credentials, and all configured mapped groups.
3. tht auth check --interactive repeats live diagnosis and additionally validates a device-flow identity and its direct groups claim when Device Authorization is available.
4. Workspace Test performs aggregate live workspace and authentication validation.

The live CLI forms are:

tht auth check
tht auth check --json

For a provider that advertises Device Authorization, tht auth check --interactive presents a verification URI and one-time user code on the terminal, waits for completion, and validates a real ID token including groups. It is an operator check, not a replacement for browser login.

tht doctor emits this exact ordered report: descriptor, files, docker, compose, configuration, authentication, services, core-http, frontend-http, workspace-registry, workflow, pi. Its authentication entry is live and non-interactive. Any authentication failure makes Workspace Validate or Workspace Test non-activatable according to that surface's static or live scope.

The complete closed diagnostic-code union and exact role-to-permission expansion are in the authentication architecture.