Initial commit

docs/AUTHENTICATION_FLOW.md

@@ -0,0 +1,125 @@
+# 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**
+```env
+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**
+```typescript
+// 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.