95 lines
4.0 KiB
Markdown
95 lines
4.0 KiB
Markdown
# Generic OIDC authentication
|
|
|
|
OIDC mode supports a standards-based provider. The browser flow is generic: Authorization Code,
|
|
PKCE S256, state, nonce, issuer/signature/audience/expiry validation, and the fixed callback
|
|
`<publicUrl>/api/auth/oidc/callback`. The browser and API must use the same origin; configure the
|
|
reverse proxy to preserve that public origin and callback path.
|
|
|
|
Configure the installation with `tht`:
|
|
|
|
```sh
|
|
tht auth configure --mode oidc --public-url <https-public-origin> \
|
|
--issuer <https-issuer> --client-id <client-id> \
|
|
--authentik-base-url <https-provider-origin> \
|
|
--user-group 'TOT Users' --admin-group 'TOT Admin'
|
|
```
|
|
|
|
The OIDC client secret is supplied through the protected secret bundle under the exact key
|
|
`THT_OIDC_CLIENT_SECRET`; it is never written into `auth.yaml`. The default scopes are exactly
|
|
`openid`, `profile`, and `email`.
|
|
|
|
The non-secret OIDC configuration has this exact shape (replace angle-bracket placeholders with
|
|
operator values):
|
|
|
|
~~~yaml
|
|
version: 1
|
|
mode: oidc
|
|
publicUrl: <https-public-origin>
|
|
session:
|
|
regularTtlSeconds: 43200
|
|
regularIdleSeconds: 7200
|
|
rememberTtlSeconds: 2592000
|
|
rememberIdleSeconds: 604800
|
|
oidcTtlSeconds: 28800
|
|
oidc:
|
|
issuer: <https-issuer>
|
|
clientId: <client-id>
|
|
clientSecretRef: THT_OIDC_CLIENT_SECRET
|
|
scopes: [openid, profile, email]
|
|
groupsClaim: groups
|
|
groupCatalog:
|
|
driver: authentik
|
|
baseUrl: <https-provider-origin>
|
|
apiTokenRef: THT_AUTHENTIK_API_TOKEN
|
|
authorization:
|
|
groupRoles:
|
|
TOT Users: [user]
|
|
TOT Admin: [admin]
|
|
~~~
|
|
|
|
## The groups claim is mandatory
|
|
|
|
The ID token must contain a direct, non-empty `groups` array of strings. ThothII does not follow
|
|
distributed claims, overage links, or indirect provider expansion. Missing or malformed claims fail
|
|
closed. A browser callback exposes only HTTP 401 `oidc_callback_failed`; it never reveals whether
|
|
the claim was missing, malformed, indirect, or overage-style. The redacted diagnostic and
|
|
interactive device-flow contract uses `oidc_groups_claim_invalid` for invalid group-claim or
|
|
device-flow identity results.
|
|
|
|
Configured group names are exact and case-sensitive. The union of matched mappings determines the
|
|
Thoth roles. A token with no mapped group is authenticated but has no role and cannot use protected
|
|
routes. Additional provider groups are ignored silently, without an error or warning. Group
|
|
existence is separately proven by the configured catalog adapter; this is why a generic OIDC
|
|
provider may authenticate while still failing installation readiness.
|
|
|
|
## Checks and diagnostics
|
|
|
|
The surfaces have distinct semantics and this order is recommended:
|
|
|
|
1. Workspace Validate performs static authentication validation without contacting the provider.
|
|
2. `tht auth check` performs live, non-interactive authentication diagnosis, including discovery,
|
|
issuer/JWKS, catalog credentials, and all configured mapped groups.
|
|
3. `tht auth check --interactive` repeats live diagnosis and additionally validates a device-flow
|
|
identity and its direct `groups` claim when Device Authorization is available.
|
|
4. Workspace Test performs aggregate live workspace and authentication validation.
|
|
|
|
The live CLI forms are:
|
|
|
|
```sh
|
|
tht auth check
|
|
tht auth check --json
|
|
```
|
|
|
|
For a provider that advertises Device Authorization, `tht auth check --interactive` presents a
|
|
verification URI and one-time user code on the terminal, waits for completion, and validates a
|
|
real ID token including `groups`. It is an operator check, not a replacement for browser login.
|
|
|
|
`tht doctor` emits this exact ordered report: `descriptor`, `files`, `docker`, `compose`,
|
|
`configuration`, `authentication`, `services`, `core-http`, `frontend-http`,
|
|
`workspace-registry`, `workflow`, `pi`. Its authentication entry is live and non-interactive.
|
|
Any authentication failure makes Workspace Validate or Workspace Test non-activatable according
|
|
to that surface's static or live scope.
|
|
|
|
The complete closed diagnostic-code union and exact role-to-permission expansion are in the
|
|
[authentication architecture](../architecture/authentication.md).
|