38 lines
2.2 KiB
Markdown
38 lines
2.2 KiB
Markdown
# 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.
|