ADR-0002 — Firebase comme provider de custom tokens

Status : Accepted Date : 2026-02 (rétroactif) Deciders : équipe plateforme Nex Tickets : —

Contexte

Le flow d’authentification Nex repose sur phone + PIN côté apps mobiles. Une fois la combinaison validée par le service auth, il faut produire un token signé porté en Authorization: Bearer vers tous les services downstream.

Trois besoins :

1. Token signé asymétriquement (RS256) — services backend vérifient sans connaître la clé privée.
2. Intégration native avec Firebase Messaging (push) pour les apps mobiles.
3. Pas de réinventer une PKI interne (HSM, gestion de clés, rotation).

Décision

Le service auth génère un Firebase custom token via le SDK Admin Firebase. Le client mobile l’échange contre un ID token Firebase et l’envoie en Bearer aux services backend, qui le valident via la JWKS publique Firebase.

[App] -- phone + PIN --> [auth]
[auth] -- custom token --> [App]
[App] -- exchange custom→ID token --> [Firebase]
[App] -- Bearer <ID token> --> [orchestrator] -> downstream

Conséquences

Positives

• Zéro gestion de PKI interne, rotation des clés gérée par Firebase.
• Intégration Firebase Messaging directe (push notifications).
• Sécurité éprouvée à grande échelle.
• Vérification offline possible côté backend (cache JWKS).

Négatives / risques

• Dépendance forte à Firebase (vendor lock-in partiel). Mitigation : isoler la dépendance Firebase dans le seul service auth.
• Coût Firebase potentiellement variable.
• En cas de panne Firebase, plus d’émission de tokens (mais les tokens existants restent valides jusqu’à expiration).
• Mapping firebase_uid ↔ user_id interne à maintenir côté DB.

Alternatives écartées

• PKI interne JWT (RS256) avec rotation manuelle — coût opérationnel élevé, gestion HSM nécessaire.
• Auth0 — coût plus élevé pour le volume CEMAC, moins natif sur Firebase Messaging.
• Cognito AWS — bonne intégration AWS mais ergonomie mobile moins fluide qu’Firebase Auth.

Suivi

• Service auth porte la responsabilité unique de produire le custom token.
• Services downstream valident via JWKS Firebase publique.
• Voir /services/auth/overview pour le détail d’implémentation.
• Voir /services/auth/orchestrator-boundary pour la frontière auth ↔ orchestrator.