Why identity migrations are uniquely risky

Most system migrations affect a bounded, well-understood set of functionality. An identity system migration is different: virtually every application in an organization depends on it, often in ways that aren’t fully documented or understood until something breaks. A single overlooked integration, an unmigrated password hash format, or a role mapping that didn’t translate correctly doesn’t just affect one feature — it can lock out entire populations of users from everything at once. This outsized blast radius is exactly why identity migrations demand a fundamentally more cautious, staged approach than most other infrastructure changes.

What does “migration strategy” actually cover?

A Legacy IAM Migration Strategy is the overall plan governing how users, credentials, roles, and application integrations move from an old identity system to Keycloak — not as a single event, but as a sequenced set of phases, each with its own verification, rollback plan, and success criteria. It covers technical questions (how do we migrate password hashes without forcing every user to reset?) and organizational ones (which applications move first, and who signs off before a phase is considered complete?) together, since a migration strategy that only addresses the technical side while ignoring coordination and sequencing is incomplete.

Why does the choice of migration pattern matter so much?

There isn’t one single correct way to migrate — the right pattern depends heavily on factors like how many applications are involved, whether legacy password hashes can be technically reused, how much downtime (if any) is acceptable, and how much parallel-running complexity the organization can realistically manage during the transition. Choosing a migration pattern without carefully weighing these specific factors is one of the most common sources of trouble in real-world migrations, often discovered only partway through when an assumption turns out not to hold.

Key vocabulary, explained simply

Password hash compatibility: the single most consequential technical question

Whether a legacy system’s stored password hashes can be directly imported and used by Keycloak depends entirely on which hashing algorithm the legacy system used. Keycloak supports several common hashing algorithms directly, and where the legacy system used a compatible one, existing password hashes can often be migrated as-is — meaning a user can log in with their existing, unchanged password immediately after migration, with Keycloak transparently verifying it against the imported hash. Where the legacy algorithm isn’t natively supported, organizations generally fall back to a just-in-time re-hashing approach, where a user’s password is correctly re-hashed into a Keycloak-native format the first time they successfully authenticate post-migration, using their still-known plaintext password at that moment.

Mapping user attributes and roles into Keycloak’s data model

Beyond credentials, every legacy user record’s attributes, group memberships, and role assignments need to be deliberately mapped onto Keycloak’s own data model — its concept of user attributes, groups, and realm or client roles doesn’t necessarily align one-to-one with how a different legacy system organized the same information. This mapping work is often more time-consuming and detail-sensitive than the credential migration itself, precisely because subtle mismatches (a legacy “manager” flag that doesn’t cleanly translate to a single Keycloak role, for example) can be easy to overlook until they cause a real, visible problem for an affected user.

Federation as an alternative to full data migration

Rather than migrating user data into Keycloak’s own store at all, Keycloak’s User Storage SPI can be used to federate directly with a legacy system that remains the authoritative source of user data — Keycloak reads (and, depending on configuration, writes) directly against the legacy store in real time, rather than holding a migrated copy. This is a meaningful alternative strategic choice, particularly useful when a full data migration is judged too risky or complex to complete upfront, deferring full data migration to a later phase, or avoiding it indefinitely if the legacy store genuinely needs to remain authoritative for other reasons.

graph TB
    LEGACY[Legacy IAM System] -->|bulk export or federation| MIG[Migration Tooling]
    MIG --> KC[Keycloak]
    KC --> MAP[Attribute/Role Mapping Layer]
    LEGACY -.->|during parallel run| APPS1[Not-Yet-Migrated Apps]
    KC -.->|during parallel run| APPS2[Migrated Apps]
    U[User Login] --> ROUTE{Which system
handles this app?}
    ROUTE -->|legacy| LEGACY
    ROUTE -->|Keycloak| KC
    

Component breakdown

Common architectural patterns for the transition period

Organizations generally choose from a few well-established patterns: migrating application by application (some apps use Keycloak, others still use the legacy system, until all have moved), migrating user population by user population (a specific department or customer segment moves first), or a just-in-time, lazy migration (users are individually migrated the moment they next log in, rather than in a single bulk operation). These patterns aren’t mutually exclusive — many real migrations combine them, for example moving one low-risk application first while also lazily migrating individual users as they log into it.

Why does application-by-application sequencing matter so much?

Migrating applications one at a time, rather than attempting every integration simultaneously, dramatically limits the blast radius of any single migration problem — an issue discovered while migrating one specific, lower-risk application affects only that application’s users, rather than the entire organization at once, and provides a concrete, real-world learning opportunity that directly improves the plan for every subsequent application’s migration.

How bulk migration works internally

In a bulk migration approach, an extraction process reads user records from the legacy system — ideally through a supported export mechanism or API, rather than direct, risky database access — and transforms each record according to the organization’s attribute and role mapping plan. Transformed records are then imported into Keycloak, typically through its administrative API, with password hashes either migrated directly (where the algorithm is compatible) or marked for just-in-time re-hashing on first login. This process is generally run against a subset of users first, verified thoroughly, and only then scaled up to the full population.

How just-in-time migration works internally at login time

In a just-in-time approach, a user’s account may not exist in Keycloak at all until their first login attempt after migration begins. At that point, a custom mechanism — often built using Keycloak’s User Storage SPI or a custom authenticator — intercepts the login, checks whether the legacy system can authenticate this user successfully using the credentials they’ve just provided, and if so, creates the corresponding Keycloak user record on the spot, complete with a freshly, correctly hashed version of the password the user just proved they know. From that point forward, the user exists natively in Keycloak and no longer depends on the legacy system at all.

Handling users who never log in during the migration window

A just-in-time approach elegantly migrates active users as they naturally log in, but it leaves a real, deliberate question: what happens to users who don’t log in at all during the planned migration window — an employee on extended leave, a customer with a dormant account? Most real migration strategies combine just-in-time migration for active users with a final, smaller bulk migration pass specifically for these remaining, inactive accounts, ensuring nobody is permanently left behind on a legacy system scheduled for eventual decommissioning.

Step-by-step: a just-in-time migration login

sequenceDiagram
    participant Legacy as Legacy IAM
    participant Keycloak
    participant App as Migrated Application
    participant User

    Note over Legacy,Keycloak: Phase 1: Pilot app cut over,
JIT migration enabled
    User->>App: Logs in
    App->>Keycloak: Authentication request
    Keycloak->>Legacy: Checks if user exists locally; if not, verifies via legacy
    Legacy-->>Keycloak: Confirms credentials valid
    Keycloak->>Keycloak: Creates native user record
    Keycloak-->>App: Login successful
    Note over Legacy,Keycloak: Phase 2-N: Additional apps
cut over in planned waves
    Note over Legacy: Final phase: Remaining
inactive users bulk-migrated,
legacy decommissioned
    

Notice that the legacy system remains present and actively relied upon well into the migration timeline in this diagram — its role only diminishes gradually, application by application, rather than disappearing at a single defined moment. This gradual transition is precisely what allows problems to be caught and corrected at small scale, long before the entire organization’s identity infrastructure depends exclusively on the new system.

The lifecycle of a full legacy IAM migration project

Protecting credentials during the migration process itself

Whether migrating password hashes directly or handling plaintext passwords momentarily during a just-in-time re-hashing flow, credential data deserves careful handling throughout the entire migration pipeline — encrypted in transit and at rest wherever it’s temporarily staged, with access tightly restricted to exactly the systems and personnel that genuinely need it, and with any temporary staging data securely deleted once no longer needed.

Maintaining consistent authorization during coexistence

During a parallel-run period, it’s essential that role and permission changes made in one system (say, a user’s access being revoked in the legacy system due to an offboarding) are correctly reflected wherever that user’s access is now actually being enforced, whether that’s still the legacy system or already Keycloak. A security-relevant change made in the “wrong” system during coexistence — one that’s no longer actually the authoritative source for that specific user or application — can create a dangerous, invisible gap where access was intended to be revoked but wasn’t actually cut off anywhere that mattered.

Auditing the migration itself

Given the scale and sensitivity of a full IAM migration, maintaining a clear, comprehensive audit trail of the migration process itself — which users were migrated when, through which mechanism, with what verification — provides essential evidence for later security reviews and for reconstructing exactly what happened if a problem is discovered well after a given phase was believed complete.

Proven patterns

Anti-patterns to avoid

Best practices

Common mistakes