# 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 Workspace Validate for static authentication validation. Then run live non-interactive
   diagnosis, followed by the optional device-flow identity check:

   ```sh
   tht auth check
   tht auth check --interactive
   tht doctor --json
   ```

6. Run Workspace Test for aggregate live workspace and authentication validation. It must prove
   discovery/JWKS, catalog access, and every configured group. The diagnostic result must contain
   no secret values. `tht doctor --json` reports `authentication` after `configuration` and before
   `services` in its exact ordered checklist.

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.