Cloner une instance Keycloak ? Cet outil automatise les réécritures d'UUID
Dupliquer une instance Keycloak sur le même serveur semble simple… jusqu’à ce que Keycloak refuse l’importation en raison d’une collision de clés primaires. Un nouvel outil open source automatise le processus manuel et source d’erreurs de régénération de chaque UUID, permettant à la copie de coexister en toute sécurité avec l’original.
Le piège des UUID dans le clonage d’instance
Keycloak exporte les instances sous forme de snapshots complets de la base de données, incluant tous les rôles, clients, utilisateurs, mappers de protocoles et flux d’authentification avec leurs UUID internes identiques. Renommer l’instance dans l’export ne modifie que son nom d’affichage : les dizaines, voire centaines, d’UUID référencés dans le fichier restent intacts. Réimporter un tel fichier dans la même instance déclenche des erreurs de clés dupliquées, car les clés primaires existent déjà. Cette limitation est documentée en amont dans keycloak/keycloak#24770, où l’exportateur n’est pas conçu pour produire un artefact compatible avec une réimportation dans la même instance.
Les corrections manuelles ne sont pas viables
En théorie, on pourrait ouvrir le JSON, remplacer chaque UUID par un nouveau, puis cartographier méticuleusement chaque ancien UUID vers le nouveau pour préserver les références croisées. Pour une instance réduite, c’est fastidieux mais faisable. Dans un environnement de production avec des rôles personnalisés, plusieurs clients, fournisseurs d’identité et flux d’authentification, le nombre d’UUID peut dépasser la centaine. Une seule référence omise peut corrompre silencieusement un flux de connexion au lieu de provoquer une erreur explicite à l’importation, laissant les administrateurs dans l’ignorance jusqu’à ce que les utilisateurs signalent des dysfonctionnements.
keycloak-realm-clone automatise la réécriture
Le CLI léger Node.js keycloak-realm-clone gère automatiquement la réattribution des UUID. Lancez-le sans installation préalable :
npx keycloak-realm-clone realm-export.json myrealm-dev
L’outil lit l’export, génère un nouveau fichier nommé myrealm-dev-realm-export.json, et affiche un résumé de toutes les modifications. Les options incluent des chemins de sortie personnalisés, un remplacement manuel du nom de l’instance source, et un mode de simulation pour inspection avant écriture.
En coulisses, il réécrit chaque valeur en forme d’UUID — identifiants de rôles, de clients, d’utilisateurs, références de comptes de service, identifiants de mappers de protocoles, identifiants de composants et identifiants de flux d’authentification — en utilisant une table de correspondance unique entre anciens et nouveaux UUID. Cette table garantit que les références d’un rôle vers son conteneur, d’un client vers son compte de service, ou d’un flux vers sa séquence d’exécution restent intactes après la réécriture.
Pourquoi c’est important
Pour les équipes qui déploient plusieurs environnements à partir de la même instance, cet outil supprime des heures de modifications manuelles et élimine le risque de défaillances silencieuses pouvant n’apparaître qu’après l’impact sur les utilisateurs. Il transforme un processus fragile et ponctuel en une étape d’automatisation reproductible, rendant le clonage d’instances sur la même instance Keycloak à la fois sûr et pratique.
Source : DEV Community. Synthèse éditoriale assistée par IA — TechnoExpress.