README

Clinch is a lightweight, self-hosted identity & SSO portal for home-labs. It gives you one place to manage people and lets any web app authenticate against it without keeping its own user table.

Core behaviour

First-run wizard → initial user becomes admin.

Admin dashboard → create / disable / delete users.

SMTP integration → send: – invitation links (one-time token) – password-reset links – 2FA back-up codes

Optional per-user TOTP (QR code + scratch codes).

Auth mechanisms exposed to client apps

OpenID Connect (OIDC) Standard OAuth2/OIDC provider endpoints (/.well-known/openid-configuration, /authorize, /token, /userinfo). Client apps (Audiobookshelf, Kavita, Grafana, …) redirect to Clinch for login; Clinch returns ID- and access-tokens.

Trusted-Header SSO (a.k.a. ForwardAuth) Reverse-proxy (Caddy, Traefik, Nginx) sends every request to clinch:9000/api/verify.

200 → proxy injects headers Remote-User, Remote-Groups, Remote-Email and forwards to the app. 401/403 → proxy redirects browser to Clinch login page; after login user is bounced back to the original URL. Apps that speak OIDC use method 1; apps that only need “who is it?” headers behind a proxy use method 2.

• Configuration ENV files

• Database creation SQLite only

• How to run the test suite

• Services (job queues, cache servers, search engines, etc.)

• Deployment instructions Docker