veza/veza-backend-api/docs/AUTH.md

Authentification & Sécurité (PR-2)

Ce document décrit les mécanismes d'authentification sécurisée mis en place sur le backend Veza.

1. Mécanisme JWT

L'authentification repose sur des tokens JWT (JSON Web Tokens) signés en HS256.

Structure du Token

• Header:
  • alg: HS256 (Strictement vérifié, none ou RS256 rejetés)
  • typ: JWT
• Payload (Claims):
  • sub (Subject): UUID de l'utilisateur
  • iss (Issuer): veza-api (Vérifié strictement)
  • aud (Audience): veza-app (Vérifié strictement)
  • exp (Expiration): Timestamp Unix
  • iat (Issued At): Timestamp Unix
  • token_version: Entier (Utilisé pour la révocation)
  • role: Rôle de l'utilisateur (user, admin, etc.)

2. Révocation de Token (TokenVersion)

Pour permettre la révocation immédiate des tokens (stateless) sans blacklist Redis complexe, nous utilisons le concept de TokenVersion.

1. Chaque utilisateur possède un champ token_version en base de données (entier, défaut 1).
2. Lors du login, le JWT généré inclut ce token_version dans ses claims.
3. À chaque requête authentifiée, le middleware :
   • Valide la signature du JWT.
   • Charge l'utilisateur depuis la DB.
   • Compare claim.token_version avec db_user.token_version.
   • Si différent : Rejet immédiat (401 Token revoked).

Cas d'usage:

• Logout "Global" : On incrémente db_user.token_version. Tous les anciens tokens deviennent invalides instantanément.
• Changement de mot de passe : Incrémentation automatique.
• Compte compromis : Incrémentation manuelle par admin.

3. Sécurité Renforcée (P1)

Validation Stricte

Le backend rejette tout token qui ne respecte pas strictement :

• alg: Doit être HS256.
• iss: Doit correspondre à la config (JWT_ISSUER ou défaut veza-api).
• aud: Doit correspondre à la config (JWT_AUDIENCE ou défaut veza-app).

Headers requis

• Authorization: Bearer <token>

4. Tests et Vérification

Pour vérifier la robustesse de l'auth :

• Tenter de changer l'algo en none -> 401.
• Modifier l'audience -> 401.
• Utiliser un token d'une version n-1 -> 401.

Voir tests/verify_auth.sh pour les tests automatisés.