Bincio Auth

bincio_auth è il servizio centralizzato di autenticazione per tutta la suite Bincio. Gestisce utenti, sessioni, inviti e funge da Identity Provider OIDC per Gitea e le app mobile.

Repository: git.bincio.org/bincio/bincio_auth · Produzione: bincio.org

Cosa fa

• Login, logout, registrazione tramite codice invito
• Emette JWT firmati che tutti i servizi validano localmente (nessun round-trip al server di auth per ogni richiesta)
• Identity Provider OIDC completo (Authorization Code Flow + PKCE): Gitea usa “Sign in with Bincio”
• Reset password: codici admin + self-service via email
• Gestione inviti per utenti e admin
• Interfaccia web Astro: login, registrazione, reset password, dashboard

Modello JWT

Il cookie bincio_session contiene un JWT, non un token opaco. Il payload include:

sub, display_name, is_admin, wiki_access, activity_access, exp

I servizi consumer (bincio wiki, bincioactivity, bincio planner) decodificano il JWT localmente con il segreto condiviso (BINCIO_AUTH_JWT_SECRET) — zero query al database per autenticare una richiesta.

Il cookie è impostato su dominio .bincio.org, quindi è automaticamente disponibile su wiki.bincio.org, activity.bincio.org, planner.bincio.org.

OIDC (RS256)

bincio_auth è un IdP OIDC completo. Gitea è configurato con “Generic OAuth2” che punta a bincio.org. Al primo login, Gitea crea automaticamente l’account utente.

Endpoint disponibili:

Endpoint	Scopo
GET /.well-known/openid-configuration	Discovery OIDC
GET /.well-known/jwks.json	Chiave pubblica RSA per verifica token
GET /oauth2/authorize	Login + consenso, emette auth code
POST /oauth2/token	Scambia auth code per id_token RS256
GET /oauth2/userinfo	Profilo utente dall’access token

PKCE (code_challenge / code_verifier) è supportato per client pubblici come l’app mobile.

API principale

Metodo	Path	Descrizione
POST	/api/auth/login	Login → JWT nel cookie
POST	/api/auth/logout	Cancella cookie
POST	/api/register	Registrazione con codice invito
GET	/api/me	Utente corrente
GET/POST	/api/invites	Lista/crea inviti
GET	/api/admin/users	Lista utenti (solo admin)

Controllo accessi

Ogni utente ha tre flag booleani:

• wiki_access — accesso a wiki.bincio.org (default: sì)
• activity_access — accesso a activity.bincio.org e planner.bincio.org (default: no, attivato dall’invito)
• is_admin — accesso alle funzioni di amministrazione

Gli inviti possono propagare activity_access al nuovo utente.

Stack

Componente	Tecnologia
Server	Python, FastAPI, uvicorn
Frontend	Astro + Svelte
Database	SQLite
Token	PyJWT (HS256 session, RS256 OIDC)
Crypto	cryptography (RSA keypair)
Password	bcrypt