Refactoring - Version OK

CORRECTION_KEYCLOAK_MAPPER.md

@@ -0,0 +1,193 @@
+# 🔧 Correction du Mapper Keycloak - Problème realm_access dupliqué
+
+**Date :** 17 novembre 2025  
+**Problème :** Token JWT invalide avec `realm_access` dupliqué  
+**Impact :** Vérification du token désactivée (sécurité réduite)
+
+---
+
+## 🚨 PROBLÈME IDENTIFIÉ
+
+Le token JWT généré par Keycloak contient `realm_access` **deux fois** avec des types différents :
+
+```json
+{
+  "realm_access": {
+    "roles": ["SUPER_ADMIN", "offline_access", ...]
+  },
+  "realm_access": ["SUPER_ADMIN", "offline_access", ...]
+}
+```
+
+Cela crée un **JSON invalide** car une clé ne peut pas apparaître deux fois dans un objet JSON.
+
+**Erreur Quarkus :**
+```
+Unable to parse what was expected to be the JWT Claim Set JSON
+Additional details: [[16] Invalid JSON.]
+```
+
+---
+
+## 🔍 CAUSE
+
+Un **mapper de protocole** dans Keycloak crée `realm_access` comme tableau, alors que le mapper standard crée déjà `realm_access.roles` comme objet.
+
+**Mappers en conflit :**
+1. Mapper standard Keycloak : Crée `realm_access.roles` (objet) ✅
+2. Mapper personnalisé : Crée `realm_access` (tableau) ❌
+
+---
+
+## ✅ SOLUTION
+
+### Étape 1 : Identifier le mapper problématique
+
+1. **Se connecter à Keycloak Admin Console**
+   - URL : `https://security.lions.dev/admin`
+   - Realm : `unionflow`
+
+2. **Naviguer vers le client**
+   - Menu : `Clients` → `unionflow-client`
+   - Onglet : `Mappers`
+
+3. **Identifier le mapper en double**
+   - Chercher un mapper qui crée `realm_access` comme tableau
+   - Le mapper standard devrait créer `realm_access.roles` (objet)
+   - Un mapper personnalisé crée probablement `realm_access` (tableau)
+
+### Étape 2 : Supprimer ou corriger le mapper
+
+**Option A : Supprimer le mapper en double (RECOMMANDÉ)**
+
+1. Dans la liste des mappers, identifier celui qui crée `realm_access` comme tableau
+2. Cliquer sur le mapper
+3. Vérifier le `Token Claim Name` : s'il est `realm_access` (sans `.roles`), c'est le problème
+4. **Supprimer ce mapper**
+
+**Option B : Corriger le mapper**
+
+1. Cliquer sur le mapper problématique
+2. Modifier le `Token Claim Name` de `realm_access` vers `realm_access.roles`
+3. Ou changer le type de mapper pour qu'il crée un objet au lieu d'un tableau
+
+### Étape 3 : Vérifier la configuration
+
+Le mapper standard Keycloak devrait être :
+- **Name** : `realm roles` (ou similaire)
+- **Mapper Type** : `User Realm Role`
+- **Token Claim Name** : `realm_access.roles` (avec `.roles`)
+- **Add to access token** : `ON`
+- **Add to ID token** : `ON` (optionnel)
+
+### Étape 4 : Réactiver la vérification du token
+
+Une fois le mapper corrigé :
+
+1. **Modifier `application.properties`**
+   ```properties
+   quarkus.oidc.verify-access-token=true
+   ```
+
+2. **Redémarrer l'application**
+
+3. **Tester l'authentification**
+   - Se connecter
+   - Vérifier les logs : plus d'erreur de parsing JSON
+   - Vérifier que les rôles sont correctement extraits
+
+---
+
+## 🔍 VÉRIFICATION
+
+### Vérifier le token JWT
+
+1. **Décoder le token** sur [jwt.io](https://jwt.io)
+2. **Vérifier la structure** :
+   ```json
+   {
+     "realm_access": {
+       "roles": ["SUPER_ADMIN", "offline_access", ...]
+     }
+   }
+   ```
+   ✅ **Correct** : `realm_access` est un objet avec `roles`
+   ❌ **Incorrect** : `realm_access` apparaît deux fois ou est un tableau
+
+### Vérifier les logs Quarkus
+
+**Avant correction :**
+```
+ERROR [io.qu.oi.ru.CodeAuthenticationMechanism] Access token verification has failed: Unable to parse...
+```
+
+**Après correction :**
+```
+INFO [io.qu.oi.ru.CodeAuthenticationMechanism] Authentication successful
+```
+
+---
+
+## 📋 CHECKLIST DE CORRECTION
+
+- [ ] Se connecter à Keycloak Admin Console
+- [ ] Aller dans `Clients` → `unionflow-client` → `Mappers`
+- [ ] Identifier le mapper qui crée `realm_access` comme tableau
+- [ ] Supprimer ou corriger le mapper problématique
+- [ ] Vérifier que seul le mapper standard existe (avec `realm_access.roles`)
+- [ ] Modifier `application.properties` : `quarkus.oidc.verify-access-token=true`
+- [ ] Redémarrer l'application
+- [ ] Tester l'authentification
+- [ ] Vérifier les logs (plus d'erreur)
+- [ ] Vérifier que les rôles sont correctement extraits
+
+---
+
+## 🔐 SÉCURITÉ
+
+**⚠️ IMPORTANT :** Actuellement, la vérification du token est **désactivée** pour contourner ce problème. Cela réduit la sécurité car :
+
+- Les tokens invalides peuvent être acceptés
+- La validation de la signature est contournée
+- Les tokens expirés peuvent être acceptés
+
+**Une fois le mapper corrigé, il est CRITIQUE de réactiver la vérification.**
+
+---
+
+## 🆘 DÉPANNAGE
+
+### Le problème persiste après correction
+
+1. **Vérifier que le mapper a bien été supprimé**
+   - Recharger la page des mappers
+   - Vérifier qu'il n'y a qu'un seul mapper pour `realm_access`
+
+2. **Vérifier le token JWT**
+   - Décoder sur jwt.io
+   - Vérifier qu'il n'y a qu'un seul `realm_access`
+
+3. **Vider le cache Keycloak**
+   - Redémarrer Keycloak si possible
+   - Ou attendre quelques minutes pour le cache
+
+4. **Vérifier les logs Keycloak**
+   - Chercher des erreurs de génération de token
+
+### Comment identifier le bon mapper
+
+**Mapper CORRECT :**
+- Token Claim Name : `realm_access.roles` (avec `.roles`)
+- Type : `User Realm Role`
+- Crée un objet : `{"realm_access": {"roles": [...]}}`
+
+**Mapper INCORRECT :**
+- Token Claim Name : `realm_access` (sans `.roles`)
+- Type : Peut être `User Realm Role` ou autre
+- Crée un tableau : `{"realm_access": [...]}`
+
+---
+
+**Date de création :** 17 novembre 2025  
+**Priorité :** 🔴 CRITIQUE - À corriger avant production
+