unionflow-mobile-apps/CORRECTION_KEYCLOAK_MAPPER.md

🔧 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 :

{
  "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

   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
2. Vérifier la structure :

   {
     "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