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 :

```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