45 lines
1.4 KiB
Markdown
45 lines
1.4 KiB
Markdown
# 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
|
||
|