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](../domains/_shared/rules/authentification.md#11-méthodes-dinscription)).

## 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

```mermaid
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](../domains/_shared/rules/authentification.md#11-méthodes-dinscription) pour la décision métier.

## Exemple d'intégration

```go
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.