Parallel Run: Keycloak migration while your current system keeps running
Parallel Run is Keymate's method for a Keycloak migration or any other IAM platform migration. Keymate runs next to your current system, and users and applications move across in groups. Your current system is retired only after the last group has moved and been validated; until then, sign-in traffic can go back to it.
Run in parallel, cut over when you're ready
During a parallel run, Keymate and your current identity system are both live. A routing rule decides which one handles each sign-in. Four routing patterns are available. Most migrations use more than one:
| Pattern | What happens | Used for |
|---|---|---|
| Shadow mode | Both systems check each sign-in; Keymate records its result but does not act on it | Comparing the two systems before Keymate decides anything |
| Application split | Some applications sign in through Keymate, the rest through the current system | Moving one application at a time |
| User flag | Each user is marked as migrated or not, and is routed by that mark | Moving defined groups, such as one department, and choosing exactly which users move next |
| Percentage split | A set share of sign-ins goes to Keymate | Raising load on Keymate gradually |
Outside shadow mode, the two systems share the sign-in traffic. Together they need enough capacity for your peak load.
If a step goes wrong, a minor problem pauses the migration while it is fixed. A major one sends traffic back to the current system. Corrupted data is restored from the last checkpoint, the last group that moved successfully. The failed group is then migrated again.
The steps, in order
The five steps of a parallel run: preparation, pilot in shadow mode, groups move one after another and each is a checkpoint, cutover, and cleanup, the one step that cannot be undone
- Preparation. Your team lists the data in the current system, maps its attributes to Keymate's, chooses the routing pattern and configures the bridge and credential sync. The rollback procedure is written down before anything moves.
- Pilot. A small group of low-risk users moves first, and their sign-in flows are checked end to end. Shadow mode is the pattern for this first check.
- Incremental migration. Groups of users or applications move one after another, while sign-in success rates and sync failures are watched. Each group is a checkpoint you can roll back to.
- Cutover. The remaining traffic moves to Keymate and the current system stops answering sign-ins. The current system stays in place, ready to take traffic back, until validation is complete.
- Cleanup. Sync and routing configurations are removed, the old system's data is archived, and the old system is retired. Cleanup is the one step that cannot be undone.
The bridge to your existing identity system
The bridge lets Keymate and your current identity system serve the same users at the same time. Which parts you use depends on what you run today.
Federation over OIDC and SAML.
Keymate connects to your OpenID Connect or SAML provider as an external identity provider. People keep signing in where they do today, and Keymate receives their identity from it.
User federation from LDAP or Active Directory.
User federation means Keymate signs users in against the directory you already run: your LDAP/AD stays the source; nothing migrates. Passwords are checked by the directory, not by Keymate.
Custom identity connectors for an older IAM product.
When a login or a user source does not speak a standard protocol, such as a national e-government login or an older IAM product, Keymate connects it through a custom identity connector on its extension points. At sign-in, the current system checks the credentials. Keymate creates the user on the first successful sign-in and stores no password of its own.
Legacy token exchange.
An application can exchange a token from your current system for a Keymate token. The token must first pass signature, issuer and expiry checks. The user does not sign in again during the parallel run.
Credential sync.
A password changed in Keymate is carried to the current system, so the same password works whichever system answers. The reverse direction, from the current system to Keymate, needs a separate mechanism. Both are set up before the parallel run starts.
Session sync.
Once the current system registers a session through the Session Sync API, Keymate links it to its own session for that user, so signing out of one ends the session in the other.
How Keymate keeps users, organizations and federation once the migration is done is on Identity.
What moves, and what your team still does
Keymate's migration extension imports organizations, departments and their hierarchy, users with their attributes and group memberships, and the templates that define department structures and custom attributes. Two things are outside it:
Access policies.
Policies from the current system are not converted by the migration extension; they move separately, through Keymate's bulk policy import.
Application code.
An application that signs in over OIDC or SAML is pointed at Keymate when its turn comes. Authentication takes over single sign-on and MFA for each application as it moves. An application that calls your current system's own API instead of OIDC or SAML needs work from its team, and legacy token exchange keeps it running until then.
Moving your realms, clients and flows to Keymate
Keymate's identity foundation is Keycloak, so realms, clients, identity providers and authentication flows are the same objects in Keymate. Realms, clients and flows move with Keycloak's own realm export and import, and user records from another system move with keymate-migrator; Keymate vs Keycloak covers custom themes and providers and what Keymate adds.
Migrating 20 million identities into Keycloak
Keymate's migrator moved more than 20 million identities from an existing IAM system, backed by PostgreSQL, into Keymate's Keycloak build on Kubernetes, while the source system was under heavy production load. Three posts published between December 2025 and February 2026 tell how it was done:
No record lost, and resumable.
Every record ended in an explicit success or failure state, failed records were retried with backoff, and a stopped migration picked up where it left off.
From 2 to 12 million records per hour.
The limit was the database, not Keycloak; the Keycloak migration tuning post gives the settings for each step.
Keycloak held up.
It handled about 95,000 concurrent requests without crashing or refusing connections.
The migrator is published on GitHub as an open-source tool under the Apache License 2.0: keymate-migrator.
Further reading
- Migrating 20M+ identities to Keycloak: the account of the 20-million-identity migration, from the constraints (no silent data loss, no uncontrolled retries, resumable runs) to the work queue and the custom Keycloak extension.
- Reactive data migration: how the migrator works, with the PostgreSQL work queue, bounded concurrency in Quarkus and Mutiny, durable retries with backoff, and a simulation against a failing Keycloak.
- Keycloak migration tuning: the metrics and settings that took the same migration from 2 million to 12 million records per hour, including PostgreSQL tuning and smaller connection pools.
Questions
Do I have to replace my current identity system to use Keymate?
No. Keymate can federate with your current identity provider over OIDC or SAML, sign users in against your LDAP or Active Directory, or connect an older IAM product through a custom identity connector, so the system you run keeps working. If you do decide to move, Parallel Run moves users and applications across in steps, with the current system live until the last step.
How do I migrate millions of users into Keycloak?
Build the migration as a long-running process that expects failures and can stop and resume where it left off. In a migration of more than 20 million identities into Keymate's Keycloak build, each record was a work item in a PostgreSQL queue with an explicit success or failure state, and failed records were retried with backoff. The limit was the database, not Keycloak. Throughput rose from 2 million to a peak of 12 million records per hour; the Keycloak migration tuning post gives the settings for each step.
Do users have to reset their passwords during the migration?
No. During the parallel run, passwords are checked where they live today: by your LDAP or Active Directory through user federation, or by your current system through a custom identity connector. Where Keymate does hold the password, credential sync carries a change made in Keymate to the current system, so the same password works whichever system answers. Credential sync is set up before the parallel run starts.
Can we roll back if something goes wrong?
Yes. Each group of users or applications is a checkpoint: a major problem sends traffic back to the current system, and corrupted data is restored from the last checkpoint and migrated again. The current system stays in place until validation after cutover is complete.
What does the migration not move?
Access policies and application code. Policies move separately, through Keymate's bulk policy import, and an application that calls your current system's own API instead of OIDC or SAML needs work from its team; legacy token exchange keeps such an application running until that work is done.
Does Keymate change how Keycloak upgrades work?
No. Upgrading to a newer Keycloak version is a different job from moving onto Keymate. The Keycloak upgrade guide lists the breaking changes of each release; Keymate ships its own Keycloak build and upgrades it as Keycloak releases come out, so your team does not upgrade it separately, and custom themes and providers you wrote follow that same guide.