# Authentik provider configuration

ThothII uses generic OIDC in the browser. Authentik provides the identity provider and group
catalog without adding a proprietary login flow.

```mermaid
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.