btpxpress-frontend/docs/AUTHENTICATION_FLOW.md

Flux d'Authentification BTP Xpress

🎯 Architecture Optimisée

L'authentification BTP Xpress utilise une redirection directe vers Keycloak sans pages intermédiaires inutiles.

🔄 Flux d'Authentification

1. Connexion

Page d'accueil → Bouton "Commencer" → /api/auth/login → Keycloak → Dashboard

Détails :

• Bouton "Commencer" : Redirige vers /api/auth/login
• API Route : /app/api/auth/login/route.ts construit l'URL Keycloak et redirige
• Keycloak : Gère l'authentification utilisateur
• Retour : Redirection vers /dashboard après succès

2. Déconnexion

Menu utilisateur → "Se déconnecter" → /api/auth/logout → Keycloak → Page d'accueil

Détails :

• Bouton déconnexion : Redirige vers /api/auth/logout
• API Route : /app/api/auth/logout/route.ts construit l'URL de déconnexion Keycloak
• Cookies : Suppression automatique des tokens
• Retour : Redirection vers / après déconnexion

3. Protection des Routes

Route protégée → Middleware → Vérification token → Si invalide → /api/auth/login

Détails :

• Middleware : /middleware.ts vérifie les tokens sur toutes les routes protégées
• Redirection automatique : Vers /api/auth/login avec paramètre redirect
• Retour intelligent : Redirection vers la page initialement demandée

📁 Structure des Fichiers

API Routes

• /app/api/auth/login/route.ts - Redirection vers Keycloak pour connexion
• /app/api/auth/logout/route.ts - Redirection vers Keycloak pour déconnexion

Pages de Fallback

• /app/not-found.tsx - Page 404

Configuration

• /middleware.ts - Protection des routes et redirections
• /contexts/AuthContext.tsx - Gestion de l'état d'authentification
• /config/keycloak.ts - Configuration Keycloak

⚙️ Configuration Keycloak

Variables d'Environnement

NEXT_PUBLIC_KEYCLOAK_URL=https://security.lions.dev
NEXT_PUBLIC_KEYCLOAK_REALM=btpxpress
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=btpxpress-frontend

URLs de Redirection Keycloak

• Connexion : ${KEYCLOAK_URL}/realms/${REALM}/protocol/openid_connect/auth
• Déconnexion : ${KEYCLOAK_URL}/realms/${REALM}/protocol/openid_connect/logout
• Inscription : ${KEYCLOAK_URL}/realms/${REALM}/protocol/openid_connect/registrations

🚀 Avantages de cette Architecture

✅ Simplicité

• Pas de pages intermédiaires inutiles
• Redirection directe vers Keycloak
• Flux utilisateur optimisé

✅ Performance

• Moins de redirections = chargement plus rapide
• Pas de JavaScript côté client pour l'authentification
• Server-side redirects plus efficaces

✅ Sécurité

• Tokens gérés côté serveur uniquement
• Pas d'exposition des tokens côté client
• Suppression automatique des cookies sensibles

✅ Maintenance

• Configuration centralisée dans les API routes
• Moins de code à maintenir
• Logique d'authentification simplifiée

🔧 Utilisation

Pour les Développeurs

// Dans un composant, pour déclencher la connexion
const handleLogin = () => {
  window.location.href = '/api/auth/login';
};

// Pour la déconnexion
const handleLogout = () => {
  window.location.href = '/api/auth/logout';
};

Pour les Utilisateurs

1. Cliquer sur "Commencer" sur la page d'accueil
2. Être redirigé automatiquement vers Keycloak
3. Se connecter avec ses identifiants
4. Être redirigé vers le dashboard BTP Xpress

🛠️ Dépannage

Si la redirection ne fonctionne pas

1. Vérifier les variables d'environnement Keycloak
2. Vérifier que Keycloak est accessible
3. Consulter les logs de l'API route
4. Utiliser la page de fallback /auth/login

En cas d'erreur d'authentification

• Les pages de fallback (/auth/login, /auth/forbidden) restent disponibles
• Les erreurs sont loggées dans la console
• Redirection automatique vers les pages d'erreur appropriées

Cette architecture garantit une expérience utilisateur fluide et une maintenance simplifiée du système d'authentification.