User Migration for Keycloak
Move users from a legacy identity provider to Keycloak without forcing a password reset. Users authenticate against the old system on first login, then migrate silently into Keycloak.
The problem
"Export and import" doesn't actually migrate users
Every Keycloak migration project hits the same wall: you can move user records, but you can't move the credentials they log in with.
Password hashes don't transfer
Legacy systems use hash algorithms Keycloak can't import — and third-party IdPs like Auth0 don't release the hashes at all.
Forced resets cause churn
Making every user reset their password is a churn event nobody wants to own. Active users complain; inactive users never come back.
Migrations stall
Teams stay on the legacy IdP, the Keycloak rollout slips by quarters, and the dual-system tax compounds.
Why we built it
Migrate users on first login, transparently
The only pattern that actually works at scale: keep the old system online, validate against it once on first login, and silently migrate the user into Keycloak.
Just-in-time migration
Keycloak calls your legacy endpoint on first login. On success, it creates the user locally and never asks the legacy system about them again.
Simple HTTP contract
Two endpoints on the legacy side: authenticate and lookup. Implementable in any language against any user store.
No forced password reset
Users log in once with their existing credential and they're migrated. The legacy system can stay online until traffic naturally drains.
Zero-churn cutover
Run Keycloak and the legacy IdP side-by-side until every active user has migrated naturally, then retire the old one.
What teams use it for
Migrate from a legacy IdP
Move off Auth0, Okta, or a homegrown user store without forcing users to reset their password. They log in once with their existing credential and they're migrated.
Phase out a custom auth system
Replace a years-old custom login system without coordinating a password reset across your entire user base.
Acquired company onboarding
Bring an acquired company's users onto the parent SSO platform without making them all create new accounts.
Zero-churn cutover
Run Keycloak and the legacy system side-by-side until every active user has migrated naturally, then retire the old one.
Key capabilities
Just-in-time migration
Implemented as a Keycloak user federation provider. On first login, Keycloak calls your legacy endpoint; on success, it creates the user locally and never asks the legacy system again.
Simple HTTP contract
The legacy side is just an authenticate endpoint and a lookup endpoint. Implementable in any language against any user store.
Get started
Install from GitHub
Federation provider JAR. Drop into your Keycloak providers directory and configure per realm.
p2-inc/keycloak-user-migrationRead the docs
Configuration and the HTTP contract your legacy endpoint needs to satisfy.
User migration docsNeed help migrating?
Phase Two offers migration services for teams moving off Auth0, Okta, or homegrown systems.
Migration support