Aller au contenu principal

Auth flow

Auralith utilise des cookies httpOnly + CSRF pour les sessions browser et des API keys bearer pour les programmatic clients. Pas de JWT en localStorage (volontaire — XSS theft).

Sessions browser (cookies)​

  • Cookie session : httpOnly (pas accessible en JS), Secure (HTTPS only), SameSite=Lax. Contient le user_id signe avec SECRET_KEY.
  • Cookie csrf_token : non httpOnly (le JS doit le lire pour le placer dans X-CSRF-Token header). CSRF middleware verifie l'egalite cookie == header sur chaque requete unsafe.
  • Pas de localStorage : aucune information sensible en JS-readable.

OAuth (Google, GitHub)​

  1. Frontend redirige vers /auth/oauth/{provider}/start.
  2. Backend genere un state, pose un cookie temporaire, redirige vers le provider.
  3. Provider rappelle /auth/callback?code=...&state=....
  4. Backend verifie state, echange code contre token, recupere profile, cree ou relie le user, pose les cookies session + CSRF.

2FA TOTP​

  1. User active 2FA depuis /profile. Auralith genere un secret base32, affiche QR code (otpauth://totp/...), stocke totp_secret chiffre.
  2. User scan avec Google Authenticator / 1Password / Authy.
  3. Login : apres password ok, redirige vers /login/2fa qui demande le code 6 digits. Verifie via TOTP. Si ok, pose les cookies.
  4. Recovery codes : 10 codes one-shot generes, hashes en base. Permet de recuperer si l'authenticator est perdu.

API keys​

  • Scope par projet (creees depuis Settings projet).
  • Format : prefix_secret. Le prefix est en clair en base (pour lookup), le secret est hash bcrypt.
  • Header : Authorization: Bearer <prefix_secret>.
  • Pas de session cookie ; chaque appel est authenticate independemment.

SAML / SCIM​

Voir SAML SSO et SCIM provisioning. SAML pose les memes cookies que login local apres assertion validee. SCIM authentifie via bearer token dedie (different des API keys utilisateur).

Pieges courants​

  • Cookies bloques cross-domain : si frontend sur app.example.com et API sur api.example.com, configurer COOKIE_DOMAIN=.example.com sinon rien ne marche.
  • CSRF echoue en dev : si vous tournez frontend sur localhost:4200 et API sur localhost:8000, le middleware CSRF accepte SameSite=Lax mais refusera SameSite=Strict. Verifiez le mode.
  • 2FA backup codes mal stockes : si l'user les note dans un password manager unifie avec son login, perte du password manager = compte perdu. Recommander un stockage separe.

Voir aussi​