The best way to migrate from self-hosted Keycloak to a managed IAM solution without losing existing users

"Without losing existing users" means two different things, and conflating them is why many migrations stall halfway. The first is not losing identities: accounts, roles, memberships, history, application references — a solved problem, you export and provision via API. The second is not asking users to redo something — typically reset their password — and that is the real project constraint. The strategy that solves both is temporary coexistence through federation, with application-by-application cutover and rollback always available.

Step 1 — Inventory: what is really in the realm

Keycloak migrations rarely fail on users. They fail on a forgotten customisation: a mapper adding a claim an application uses for an authorisation check, a modified theme, a custom required action, an SPI written three years ago by someone who no longer works there.

Step 2 — Export and map the concepts

The realm export produces the full configuration in JSON: it is the formal inventory to build the map on, and also the document to archive before touching anything.

# Full export of a realm to files
bin/kc.sh export --dir /tmp/export --realm my-realm --users realm_file

# The result contains clients, roles, groups, mappers,
# identity providers and realm users.

Step 3 — The three strategies, and how to choose

The third strategy is the one that literally answers "without losing users", because it decouples the two problems: first you move the applications, then — calmly and with no imposed deadline — you move the credentials. Everything keeps working in between.

The credentials chapter, without euphemisms

Here is something commercial pages tend to skip. Keycloak stores password hashes in its own format, with its own parameters. A platform built on the principle that nobody — not even the vendor — can access or replace a user's credentials does not import hashes from another system: credentials in LoginMaster are established by the user, protected with Argon2 and a split salt between tenant and cloud, and no function exists to set them on their behalf.

It is a real constraint, and it is the same one that makes it impossible for a compromised administrator to take over accounts. There are three practical consequences, and they belong in the plan:

• Federated users are unaffected: they authenticate at Entra ID, Google Workspace or the corporate IdP, and migration is transparent for them.
• Users with local credentials establish their password on the new system through already registered verified channels, as in a normal renewal.
• Coexistence through federation lets you spread that step over time instead of concentrating it on one date, which is what makes the project acceptable.

Step 4 — Build the target tenant

The temptation is to replicate the existing configuration as faithfully as possible. That is the mistake that carries years of debt along: roles no longer used, clients of retired applications, mappers feeding claims nobody reads any more.

1. 1Create the tenant and set baseline policies: session lifetime, password requirements, allowed second-factor types, authorised email domains.
2. 2Create one project per genuinely active application, not per client present in the realm.
3. 3Recreate only the roles actually assigned to someone in the last twelve months, and document the rest as removed.
4. 4Set the 2FA policy per project: this is the moment to make the second factor mandatory on administrative panels, which in Keycloak often stayed optional.
5. 5Configure white-label: logo, colours, email templates, domain. It replaces custom themes and requires no build or deploy.

Step 5 — Migrate identities and validate with a pilot

Subject provisioning happens through the REST API or the SDKs, with a stable external identifier that lets the operation be replayed without creating duplicates.

POST /v1/projects/prj_12ab/subjects HTTP/1.1
Host: api.loginmaster.it
Authorization: Bearer ak_live_••••••••
Content-Type: application/json

{
  "type": "user",
  "externalId": "kc-9f2a7c1e",
  "roles": ["member"]
}

Use the Keycloak user identifier as externalId, not the email: it makes reconciliation between the two systems deterministic for the whole coexistence period. The full procedure, including idempotency and error handling, is in User provisioning and lifecycle via REST API and SDK.

The pilot

• Pick a low-risk but real application: a test application does not produce the problems you need.
• Involve twenty to fifty real users, from different departments, not just the technical team.
• Verify the whole cycle: login, session, renewal, logout, second factor, recovery, revocation.
• Measure the tickets generated: that is the figure that sizes the support needed for the general cutover.
• Run the pilot for at least two weeks: some problems only appear when the first long session expires.

Step 6 — Application-by-application cutover

Cutting over every application at once concentrates all risk in a single window and makes it impossible to tell which problem belongs to which integration. One at a time, with an observation window in between.

1. 1Order applications from lowest to highest risk, leaving those with the most external users last.
2. 2Before cutover, verify rollback is actually executable: restore the previous configuration in a test environment and try it.
3. 3Move the application, observe for at least three working days, then move to the next.
4. 4Monitor three indicators: successful login rate, tickets opened, application errors on token verification.
5. 5Announce each move in advance, even when nothing changes for the user: a login that looks different without warning generates phishing reports.

Step 7 — Decommission Keycloak

• Put the installation in read-only mode instead of shutting it down: rollback stays possible without restores.
• Keep it for a defined window, typically thirty to ninety days after the last cutover.
• Archive the realm export and the concept map documentation: they are the evidence of what was migrated and how.
• Only then shut the infrastructure down and close the cost lines: machines, database, backups, certificates, monitoring.
• Update the processing register and the security documentation: the identity source has changed.

What really changes, beyond the platform

Keycloak is a very good product. The reason people migrate is rarely a missing feature: it is the operational cost of running it, which is real and appears on no licence line.

The last two rows are architectural differences, not economic ones, and they are the ones some organisations discover they want only after filling in an enterprise customer's security questionnaire. The extended comparison is on Keycloak alternative, the general picture of migration paths on IAM migration, and the total cost of ownership comparison in Self-hosted Keycloak vs managed IAM.

Who wrote this guide

LoginMaster is the IAM platform of CDBKR S.r.l., an Italian company that designs and operates authentication infrastructure for software houses, MSPs and European enterprise organisations. The path described — inventory, concept map, pilot, progressive cutover with rollback available — is the one the team applies in migration projects, including the credentials chapter, which is tackled first precisely because it sets the schedule. To assess your own realm: contact us.