roadwave/docs/adr/008-authentification.md

ADR-008 : Authentification et Gestion d'Identité

Statut : Accepté Date : 2025-01-18

Contexte

RoadWave nécessite un système d'authentification sécurisé pour mobile (iOS/Android), scalable jusqu'à 10M utilisateurs, avec contraintes de coût réduit et conformité RGPD.

Exigence de souveraineté : En cohérence avec ADR-004 (CDN 100% français), les données d'authentification doivent être hébergées en France pour garantir une souveraineté totale.

Décision

Zitadel self-hosted sur OVH France pour l'IAM avec validation JWT locale côté API Go.

Méthode d'authentification : Email/Password uniquement (pas d'OAuth tiers)

• ✅ Authentification native Zitadel (email + mot de passe)
• ❌ Pas de fournisseurs OAuth externes (Google, Apple, Facebook)
• Protocole : OAuth2 PKCE (entre app mobile et Zitadel uniquement)

Architecture de déploiement :

• Container Docker sur le même VPS OVH (Gravelines, France) que l'API
• Base de données PostgreSQL partagée avec RoadWave (séparation logique par schéma)
• Aucune donnée d'authentification ne transite par des serveurs tiers

📋 Clarification : OAuth2 PKCE est le protocole technique utilisé entre l'app mobile et Zitadel. Ce n'est PAS pour des fournisseurs tiers. L'authentification reste 100% email/password native (voir Règle 01).

Alternatives considérées

Solution	Coût (10M users)	Performance	Simplicité	Intégration Go
Zitadel	200-500€/mois	Excellente	Élevée	SDK natif
Supabase Auth	32K€/mois	Excellente	Élevée	REST API
Keycloak	200-800€/mois	Bonne	Faible	Lib tierce
Auth0	50K€+/mois	Excellente	Élevée	SDK natif
JWT Custom	0€ (dev)	Excellente	Moyenne	Natif

Justification

• Souveraineté garantie : Self-hosting sur OVH France (Gravelines) = 100% des données en France, cohérent avec ADR-004
• Coût maîtrisé : 100x moins cher que Supabase/Auth0 à 10M users (pas de coût par utilisateur actif)
• Performance : JWT validation locale = 0 latence auth sur chaque requête API
• Stack alignée : Go + PostgreSQL + Redis (déjà dans RoadWave)
• Scalabilité prouvée : Clients avec 2.3M tenants, architecture event-sourced
• RGPD natif : Open source, contrôle total des données, DPA non nécessaire (pas de sous-traitant)
• Standards ouverts : OpenID Connect certifié (pas de vendor lock-in, migration facile si besoin)

Architecture

graph TB
    subgraph Mobile["Mobile Apps (iOS/Android)"]
        User["User: email + password<br/>Protocol: OAuth2 PKCE<br/>(pas de provider tiers!)"]
    end

    subgraph OVH["OVH VPS Essential (Gravelines, FR)"]
        subgraph Zitadel["Zitadel IdP (Docker)"]
            ZitadelAuth["Port 8081<br/>Self-hosted<br/>Email/Pass native"]
        end

        subgraph API["Go + Fiber API (RoadWave)"]
            APIValidation["Port 8080<br/>Validation JWT locale"]
        end

        subgraph DB["PostgreSQL + PostGIS"]
            Schemas["Schémas:<br/>- roadwave<br/>- zitadel"]
        end
    end

    User -->|HTTPS| ZitadelAuth
    ZitadelAuth -->|JWT token| APIValidation
    APIValidation --> Schemas

    classDef mobileStyle fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef ovhStyle fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef serviceStyle fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef dbStyle fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

    class Mobile mobileStyle
    class OVH ovhStyle
    class Zitadel,API serviceStyle
    class DB dbStyle

Données 100% hébergées en France (souveraineté totale) Authentification 100% email/password (pas de Google/Apple/Facebook)

OAuth2 PKCE : Protocole vs Fournisseurs Tiers

Clarification importante pour éviter toute confusion :

Concept	RoadWave	Explication
OAuth2 PKCE (protocole)	✅ Utilisé	Protocole sécurisé entre app mobile et Zitadel (flow d'authentification)
OAuth providers tiers	❌ Pas utilisé	Google, Apple, Facebook, etc. ne sont PAS intégrés
Méthode d'authentification	✅ Email/Password	Formulaire natif Zitadel uniquement

Flow d'authentification :

1. User ouvre app mobile → formulaire email/password
2. App mobile → Zitadel (OAuth2 PKCE) → validation email/password
3. Zitadel → JWT access token + refresh token
4. App mobile → Go API avec JWT → validation locale

Ce que nous N'UTILISONS PAS :

• ❌ "Sign in with Google"
• ❌ "Sign in with Apple"
• ❌ "Sign in with Facebook"
• ❌ Aucun autre fournisseur externe

Pourquoi OAuth2 alors ? :

• OAuth2 PKCE est le standard moderne pour auth mobile (sécurisé, refresh tokens, etc.)
• Zitadel implémente OAuth2/OIDC comme protocole, mais l'auth reste email/password
• Alternative serait session cookies (moins adapté mobile) ou JWT custom (réinventer la roue)

📋 Référence : Voir Règle 01 - Méthodes d'Inscription pour la décision métier.

Exemple d'intégration

import "github.com/zitadel/zitadel-go/v3/pkg/authorization/oauth"

// Validation JWT locale haute performance
verifier := oauth.WithJWT(config)
app.Use(verifier.Middleware())

// Accès aux claims
userID := ctx.Locals("sub").(string)

Conséquences

Positives

• ✅ Souveraineté totale : Données 100% en France (OVH Gravelines), contrôle complet
• ✅ Coût prévisible : Pas de surprise à la croissance (pas de facturation par utilisateur)
• ✅ Performance : Latence minimale (même VPS que l'API)
• ✅ Fonctionnalités avancées : MFA, passkeys, SSO disponibles gratuitement
• ✅ Conformité RGPD : Pas de DPA nécessaire (pas de sous-traitant externe)
• ✅ Standards ouverts : Migration facile vers autre solution si besoin

Négatives

• ❌ Maintenance : Nécessite monitoring et mises à jour régulières
• ❌ Complexité initiale : Configuration PostgreSQL schema partagé
• ❌ Backup : Responsabilité de sauvegarder les données utilisateurs
• ❌ Scaling : Migration Kubernetes nécessaire au-delà de 500K utilisateurs

Déploiement

• MVP (0-20K) : Docker sur VPS OVH Essential (coût inclus)
• Growth (20K-500K) : Même architecture, VPS plus puissant si besoin
• Scale (500K+) : Migration Kubernetes managé avec haute disponibilité

Coût Estimé

Phase	Utilisateurs	Coût Zitadel/mois
MVP	0-20K	0€ (inclus VPS)
Growth	20K-500K	0€ (inclus VPS)
Scale	500K+	50-100€ (instance K8s dédiée)

Comparaison : Auth0 coûterait 50K€/mois pour 10M utilisateurs vs 100€/mois en self-hosted.