ThothII/docs/install/authentik.md

Authentik provider setup

Authentik is the first certified provider for PSD acceptance. The ThothII browser protocol remains generic OIDC; these steps configure the provider-specific group catalog only.

1. Create an OAuth2/OIDC application and provider in Authentik. Register exactly <publicUrl>/api/auth/oidc/callback as the callback and enable openid, profile, and email.

2. Configure the provider so the ID token contains a direct groups array of strings. Verify the claim with a disposable test identity before running acceptance.

3. Create a dedicated API service account for the group catalog. Grant group-view-only privilege; do not grant write, user-management, or directory-administration privilege. Put its bearer value in the protected bundle under THT_AUTHENTIK_API_TOKEN.

4. Create or confirm the exact groups TOT Users and TOT Admin. Map them explicitly in auth.yaml to user and admin, respectively. Keep other upstream groups out of the mapping.

5. Run the static check and then the live interactive check:

   tht auth check
   tht auth check --interactive
   tht doctor --json
   

6. Run workspace Validate and then workspace Test. Test must prove discovery/JWKS, catalog access, and every configured group. The diagnostic result must contain no secret values.

Only configured exact group names are queried. Additional Authentik or directory groups are ignored silently, without a warning. A mapped group absent from Authentik fails closed with oidc_mapped_group_missing; an ambiguous exact-name result uses oidc_mapped_group_ambiguous. A group visible only in an upstream directory but not represented in Authentik is missing from ThothII’s catalog and must not be treated as present.

Rotate the two credentials independently through the protected secret-file procedure, then repeat tht auth check and workspace Test. Never put either value in this guide, YAML, shell history, diagnostic output, or acceptance evidence.