docs(auth): document local OIDC and Authentik operation

2026-08-18 03:07:33 +02:00
parent 6ec5b76c54
commit f4f38717e1
17 changed files with 407 additions and 0 deletions
@@ -0,0 +1,34 @@
+# 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:
+
+   ```sh
+   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.