Après avoir vu plusieurs tutoriels autour d’Authentik, je vous propose aujourd’hui d’aller un peu plus loin en abordant une migration complète depuis Keycloak. Dans ce guide, nous allons voir comment transférer les utilisateurs et les groupes d’un royaume Keycloak vers Authentik à l’aide d’un script PowerShell que j’ai précédemment réalisé.
L’objectif est de vous offrir une méthode simple, reproductible et entièrement automatisable pour basculer votre gestion d’identités sans complexité inutile.
Sommaire
Prérequis
- Un ordinateur sous Windows avec PowerShell installé (version 5.1 ou PowerShell 7+).
- Un environnement Authentik déjà déployé, peu importe la méthode (Docker, Kubernetes, VM…).
- Un accès administrateur à Keycloak.
- Un accès administrateur à Authentik, pour pouvoir créer utilisateurs et groupes via l’API.
Objectifs du tutoriel
L’objectif de ce guide est de vous montrer comment migrer automatiquement :
- Les utilisateurs d’un royaume Keycloak vers Authentik
- Les groupes associés, avec leur hiérarchie et leurs memberships
Ce que le script ne fait pas
Pour rester simple et focalisé sur les identités, le script ne couvre pas les points suivants :
- Migration des applications (clients) de Keycloak vers Authentik
- Migration ou recréation des providers / méthodes d’authentification dans Authentik
- Reconfiguration des applications pour qu’elles utilisent Authentik au lieu de Keycloak
Ces étapes devront être effectuées manuellement ou via d’autres scripts/outils selon votre architecture.
Comment migrer vos utilisateurs et groupes de Keycloak vers Authentik
Pour commencer, télécharger le script qui est disponible à cette adresse : Sync-Keycloak-to-Authentik.ps1
Ouvrir le script et modifier les variables suivantes pour les faire correspondre à votre environnement :
Variables principales à configurer :
| Variable | Description |
|---|---|
$KeycloakBaseUrl | URL du serveur Keycloak |
$KeycloakRealm | Realm Keycloak à synchroniser |
$KeycloakClientId | Client utilisé pour l’authentification (ex: admin-cli) |
$KeycloakUsername | Compte admin Keycloak |
$KeycloakPassword | Mot de passe du compte admin Keycloak |
$AuthentikBaseUrl | URL du serveur Authentik |
$AuthentikToken | Token API Authentik |
$AuthentikDefaultPath | Chemin dans Authentik où créer les utilisateurs |
$TokenRefreshInterval | Nombre d’itérations avant régénération du token Keycloak |
$Transcript | Activation de la journalisation (True/False) |
$TempPath | Dossier temporaire pour les logs |
$TranscriptLogFile | Nom du fichier log généré |
Une fois les variables configurées dans votre script PowerShell (URL de Keycloak, token, URL d’Authentik, clés API, royaume à exporter, etc.), vous pouvez lancer la migration en toute simplicité.
Le script va automatiquement :
- Récupérer les utilisateurs du royaume Keycloak
- Récupérer les groupes et leur structure
- Recréer ces éléments dans Authentik via l’API
L’un des avantages de ce script est qu’il peut être exécuté plusieurs fois sans aucun problème.
Il effectue en effet les vérifications nécessaires pour éviter les doublons :
- Un groupe déjà migré ne sera pas recréé
- Un utilisateur existant n’écrasera pas les données déjà présentes
- Seuls les éléments manquants seront ajoutés
Cela permet d’effectuer la migration par itérations, ou de réexécuter le script en cas d’ajustement, sans risque pour votre environnement.
Gestion de l’External ID et configuration du provider OpenID
Dans certains environnements, les applications ne s’appuient pas sur l’adresse e-mail ou le nom d’utilisateur pour identifier un compte, mais utilisent à la place un identifiant interne propre au fournisseur d’identité.
Lors d’une migration depuis Keycloak, il peut donc être nécessaire de conserver cet identifiant unique pour garantir que les applications continuent de reconnaître correctement les utilisateurs.
Pourquoi utiliser l’ID Keycloak comme Identifiant Unique ?
Chaque utilisateur dans Keycloak possède un ID interne, un UUID stable et immuable.
Ce script de migration synchronise cet identifiant vers Authentik sous forme d’External ID, afin de :
- Préserver l’identité unique d’un utilisateur côté application
- Éviter la création de nouveaux comptes non reconnus
- Assurer une continuité transparente après la bascule vers Authentik
Ainsi, une application qui utilisait l’ID Keycloak pour identifier un utilisateur pourra continuer à fonctionner avec Authentik.
Limitation : uniquement pour les applications utilisant l’ID interne
Cette partie ne concerne que les applications qui reposent sur l’ID interne du fournisseur d’identité comme identifiant de référence.
Dans de nombreux cas, l’identifiant unique utilisé est simplement :
- l’adresse e-mail,
- ou le username.
Pour ces applications, aucune configuration supplémentaire n’est nécessaire.
Configurer Authentik pour utiliser : external_id
Depuis l’interface d’administration dans Authentik, dérouler le menu Customization et aller sur Property Mapping et cliquer sur le bouton Créer 1.
Ensuite créer la propriété comme sur la capture ci-dessous, le nom de la portée doit être openid.
L’expression :
Ensuite dans la configuration du provider OpenID de l’application, dans la partie Paramètres avancés du protocole, retirer authentik default OAuth Mapping OpenID ‘openid’ et ajouter le Scope que vous venez de créer.
Conclusion
Migrer vos utilisateurs et groupes de Keycloak vers Authentik peut sembler complexe au premier abord, mais avec un script PowerShell bien conçu, la procédure devient simple, rapide et répétable.
En utilisant l’ID Keycloak comme External ID et en configurant correctement le provider OpenID dans Authentik, vous assurez une continuité transparente pour vos applications et une gestion centralisée des identités.
Cette méthode vous permet de sécuriser vos données, de limiter les erreurs et de garder la maîtrise de votre environnement d’identité tout en profitant des fonctionnalités modernes d’Authentik
FAQ
Le script peut-il écraser des utilisateurs existants dans Authentik ?
Non. Le script effectue des vérifications pour éviter les doublons. Les utilisateurs ou groupes déjà présents ne seront pas recréés.
Est-ce que les mots de passe sont migrés ?
Non. Les mots de passe ne sont pas transférés. Les utilisateurs devront soit réinitialiser leur mot de passe via Authentik, soit se connecter via un provider externe si configuré.
Peut-on migrer plusieurs royaumes Keycloak avec le même script ?
Oui, mais chaque royaume doit être traité séparément et les variables du script ajustées pour chaque migration.
Le script migre-t-il les applications et les providers OpenID ?
Non. Seuls les utilisateurs et groupes sont migrés. La configuration des applications et providers doit être réalisée manuellement.
Que faire si une application utilise l’e-mail comme identifiant au lieu de l’ID Keycloak ?
Dans ce cas, aucune action spéciale n’est nécessaire. Authentik pourra utiliser l’e-mail comme identifiant unique pour l’application.
