ThothII/docs/install/authentik.md

Authentik provider configuration

For full with direct OIDC, ThothII uses generic OIDC in the browser. Authentik provides the identity provider and group catalog without adding a proprietary flow. The provider/client/group setup below applies to that case only.

For embedded in Omics, retain Omics's existing Authentik authentication and configure ThothII as upstream. Omics verifies datamart_builder.access and administrator status and the proxy supplies the identity; no additional ThothII OIDC client, login or local user is required for that path. Follow the portal integration guide.

sequenceDiagram
    participant Browser
    participant ThothII
    participant Authentik
    Browser->>ThothII: Sign in
    ThothII->>Authentik: Authorization Code with PKCE
    Authentik-->>Browser: Login and consent
    Browser->>ThothII: Callback with code
    ThothII->>Authentik: Token exchange
    Authentik-->>ThothII: Identity and groups
    ThothII-->>Browser: Opaque session

OIDC provider

1. Create an OAuth2/OIDC application and provider.
2. Register exactly PUBLIC_URL/api/auth/oidc/callback.
3. Enable the openid, profile, and email scopes.
4. Configure a direct groups claim as an array of strings.

Group catalog

Create a dedicated service account with read-only access to groups. Store its token in the protected bundle as THT_AUTHENTIK_API_TOKEN.

Map the exact enterprise group names to the ThothII user and admin roles in auth.yaml. Unmapped groups are ignored. A configured group that does not exist produces a closed error.

Diagnostics

tht auth check checks discovery, the issuer, JWKS, catalog access, and the configured groups. The --interactive option also verifies identity through device flow when the provider supports it.

Rotate the OIDC secret and group-catalog token separately. Neither may appear in YAML, shell history, logs, or diagnostic output.