Keycloak migration service for hosted or legacy identity

What a Keycloak migration involves

A Keycloak migration moves more than user records. The identity estate includes user accounts, password credentials, groups and roles, client registrations, redirect URIs, sign-in flows (browser flows, required actions, MFA settings), and federated or social identities linked to each user. Each of these has a different export path and a different failure mode, so the inventory should cover all of them before anyone chooses a tool. Confirm which items your current platform can export in full, and which must be recreated by hand.

Identity is harder to move than an ordinary application because of two things. First, password hashes are only usable if the target can verify them. Some platforms export hashes in a format Keycloak can import directly, others expose no hashes at all, and in that case users must reset passwords or be migrated on first login through a custom user storage provider. Second, every token carries an issuer value. Once applications validate tokens from the new issuer, their configuration, signing keys and discovery URLs change, and sessions issued by the old issuer stop being accepted. Plan the cutover around these two facts, not around the application move alone.

The three common starting points differ in what you can take with you. A hosted identity service usually allows user and client export through its management API, but hash export and some flow configuration may be restricted, so confirm the exact export options with the vendor. Red Hat build of Keycloak replaces Red Hat Single Sign-On and is a supported distribution of the open source project, so realm exports are often close to portable, but the target version and database schema must be checked against Red Hat's product page, which listed version 26.6 as latest when this was written. An older WildFly-based Keycloak needs a version path: confirm which release you run and read the upgrade notes for every intermediate version before moving data.

Short answer: a small estate with a few clients, exportable credentials and no regulated data is often handled in-house by a team that already runs the applications. A larger estate, many realms, federated directories or a regulated environment usually benefits from a partner for cutover design and verification, because the hard work is in sequencing, rollback and proof that each application signs in correctly. Ask any partner to put the export method, hash handling, the side-by-side period and the rollback point in the written scope.

What the migration work includes

A Keycloak migration moves users, clients and sign-in behavior from the source identity service to the target realm in controlled steps. Each work package below ends with a deliverable you keep, whether or not you continue with DeployOpen.

Source inventory and mapping

We catalog every realm, client, identity provider, user store, theme, custom authenticator and token mapper on the source system, then map each one to a Keycloak equivalent or a decision to retire it. Check that the inventory covers applications nobody has logged into recently, since these often hide undocumented redirect URIs and service accounts.

Target realm and client design

We design the target realm structure, client types, scopes, role and group model, and token lifetimes before any data moves. Decisions such as one realm or several, confidential or public clients, and where custom claims are added are hard to reverse once applications depend on them, so confirm them with application owners in writing.

User and credential migration

We move user records, attributes, group memberships and credentials, and set up how password hashes are verified and rehashed. Passwords stored with a hash algorithm Keycloak cannot verify need a plan such as forced reset or lazy migration, and you should confirm which hash formats the source exports before the project is scoped.

Client-by-client cutover

Each application is moved in its own change window with a documented switch of issuer, client ID, secret and redirect URIs. We produce a cutover checklist per client that names the owner, the test accounts, the rollback step and the sign-off, so no application changes identity provider without a named person accepting it.

Sign-in flow parity

We compare login, registration, password reset, MFA enrollment and logout behavior between the source and Keycloak, using a test matrix of browsers, devices and user types. Differences such as session lifetime, lockout thresholds or claim contents are recorded and either matched or accepted by the business owner, not left to surface in production.

Side-by-side operation

For a period, both systems run and users or applications are routed to one or the other in a controlled way, with the sync or re-authentication approach agreed up front. We define how account changes made in one system reach the other, and who monitors sign-in failures on both sides during that window.

Rollback and decommissioning of the source

We document how to return an application to the source system, how long that path stays open, and the conditions for shutting the source down. The decommissioning record lists retired clients, revoked service credentials, removed DNS entries and the final export kept for audit, and DeployOpen prepares this evidence while independent auditors and certification bodies decide whether it meets their criteria.

What drives migration cost and duration

This table lists the factors that change the cost and duration of a Keycloak migration, why each one matters, and how to reduce its effect before cutover.

Driver	Why it matters	How to keep it down
User count and credential types	Each user, password, OTP device and passkey needs a mapping decision, and volume extends export and validation time.	Migrate only active accounts, and inventory credential types before scheduling any load.
Password hash export	If the source cannot export password hashes, every user must reset or re-enroll at first sign-in.	Confirm export capability with the source vendor early, and plan a fallback sign-in flow for users.
Clients and protocols	Each OIDC, OAuth 2.0 or SAML 2.0 client needs its own redirect, scope and mapper review.	Export client definitions, group them by protocol, and reuse one template for each common pattern.
Custom authenticators or user storage	Custom code in the source must be rebuilt as Keycloak SPI extensions and retested against the new flows.	Remove unused flows first, and document each remaining extension before choosing a migration path.
Realms and organizations	Each realm needs its own import, admin scope and signing keys, so realm count multiplies setup and test work.	Consolidate realms where the business allows, and confirm whether the Organizations feature fits your tenancy model.
External and social identity links	Linked accounts depend on stable subject identifiers, and mismatches create duplicate users.	Map existing identifiers to linked identity records and test a sample of accounts for each provider.
Relying applications that must change	Each application that changes issuer, client ID or endpoint needs a code or configuration release.	Keep hostnames and client IDs stable where possible, and schedule application changes in groups.
Environments and sign-in paths that must match	Every environment and sign-in path needs matching configuration, which multiplies test effort.	Manage realm configuration as code, and limit identical paths to those users depend on.
Compliance evidence for cutover	Assessors may expect records of migration scope, test results, approvals and rollback decisions.	Agree the evidence list with your auditor before cutover, and capture it during testing so it is complete at cutover.

Migration phases and their outputs

The sequence moves users, clients and sign-in flows onto Keycloak in controlled stages, with each phase closing on a written output the client can review.

Inventory the source identity estate
DeployOpen catalogs the source service, its realms or tenants, user stores, applications and clients, sign-in flows, custom code and password storage. Client-side and integration owners confirm their entries. The output is a source inventory, and the phase closes when the client signs off on it as complete.
Design the target and map realms
The team maps source realms, groups, roles and client settings to Keycloak realms, clients, roles and authentication flows, and records decisions on realm boundaries, token settings and attribute handling. The output is a target design record that names each mapping and the owner who approved it.
Decide the credential strategy
The team decides how existing password hashes move, whether through a supported import of the source hash format, a custom user storage approach, or forced resets on first sign-in. Each option is tested against the source hash types. The output is a signed credential strategy decision that states the fallback if a hash cannot be imported.
Run a pilot in a non-production environment
DeployOpen loads a subset of users, clients and flows into a non-production Keycloak and tests sign-in, token claims, logout and password behavior against the agreed design. Defects go back into the design record. The output is a pilot report listing test results, open defects and the changes made to the mappings.
Rehearse the full cutover
The complete migration runs at least once in a production-like environment with real volumes, timed steps, rollback steps and communication drafts. Owners check every client against its test cases. The output is a rehearsal report and a cutover runbook with named owners, go and no-go checks, and a rollback procedure.
Cut over production by client or user group
Production moves in the order set in the runbook, usually one client or user group at a time, with sign-in monitored after each change. The team confirms that each application authenticates against Keycloak before moving the next. The output is a cutover log recording the time, scope and result of each move.
Run the side-by-side period and decommission the source
Both systems stay available for an agreed period while the team tracks sign-in errors, stragglers and user support tickets. Once the client accepts the state, the source is made read-only, its data is archived under the client's retention rules, and it is switched off. The output is a decommission record and a closure report. Ask for the phase plan with dates in the written scope.

What stays in-house and what a partner usually takes

This table shows which migration work your identity and application teams usually keep, which work a partner typically takes on, and the skills each side needs, so you can plan ownership before scoping.

Work area	Usually in-house	Usually outsourced	Skills required
Source system ownership and access	Owners of the hosted service or old Keycloak keep admin access, approve read-only export accounts and confirm what data may leave the source system	Partner documents how the source is accessed, builds the export procedure and tests it against a copy of the data	Platform administration of the source identity service, change approval, data classification
Identity policy decisions	Security and identity leads decide who may keep which credentials, MFA rules for migrated users and how dormant accounts are handled	Partner lists the policy options, maps current settings to Keycloak equivalents and flags conflicts for decision	Identity governance, MFA policy design, risk ownership
Application owner coordination	Application owners schedule their cutovers, change their own relying-party settings (redirect URIs, client secrets, issuer URLs) and sign off on test results	Partner supplies per-application cutover checklists, token claim comparisons and test scripts for each owner	Application architecture, OIDC and SAML configuration, release management
Credential and hash migration scripting	Security team reviews hash algorithms, iteration counts and the approach to users who never sign in again	Partner writes and tests the import scripts that carry password hashes and OTP secrets across, with logging and reconciliation reports	Password hashing internals, database scripting, secure handling of secrets during transfer
Keycloak realm and client configuration	Identity team defines realm structure, roles, groups and naming conventions	Partner builds realms, clients, authentication flows and identity provider settings as code or exported configuration	Keycloak administration, realm design, infrastructure as code
Sign-in flow parity testing	Business and application owners confirm that sign-in, password reset, MFA enrollment and logout behave as expected	Partner designs the test matrix covering browsers, devices, protocols and edge cases, and runs it in a non-production realm	Test automation, authentication protocol knowledge, QA processes
Token and issuer change validation	Application owners confirm that their services accept the new issuer and that required claims are present	Partner inspects issued tokens, compares claims and signing keys with the old service and reports differences	JWT and JWKS handling, claim mapping, API gateway configuration
Runbook and rollback drills	Operations owns the cutover runbook, approval gates and the on-call rota for the cutover window	Partner drafts the runbook and rollback steps and runs at least one rehearsal with the operations team	Change management, incident response, database backup and restore
Decommissioning the old service	Owners decide retention periods, archive the old configuration and remove access once the rollback window closes	Partner removes old clients, disables federation links and documents what was retired and where evidence is kept	Access review, data retention policy, infrastructure teardown

What usually goes wrong and how to prevent it

Identity migrations rarely fail in the import itself. They fail at the edges: credentials, token issuers, redirect settings and the clients nobody remembered. The cards below cover the patterns we see most often and the checks that catch them before users do.

Credentials that cannot be exported

Many hosted identity services do not export password hashes, so migrated users may be locked out on day one. Confirm with the source vendor whether hashes, TOTP secrets and WebAuthn credentials can leave the platform. Plan a fallback such as a forced reset flow or a lazy migration step, and test it with a realistic sample of accounts.

Password hash algorithms the target does not verify

Keycloak verifies several hash algorithms, but an exported hash from another system may use a format or parameter set that the target cannot check as expected. Before the full import, test a sample of each hash type against a test realm. Where a hash is unsupported, decide between a reset campaign and a custom credential step, and document which path applies to which users.

Issuer and JWKS changes at cutover

Changing the issuer URL or signing keys breaks every relying application that validates tokens against the old issuer or a cached JWKS. Inventory each client's issuer and JWKS configuration, including APIs and gateways that verify tokens offline. Keep the old keys and issuer reachable during the overlap window and confirm each relying party refreshes its key set.

Redirect URI and client secret gaps

Clients often fail at cutover because valid redirect URIs, web origins or post-logout redirect URIs were not copied, or because client secrets were regenerated without updating the application. Compare every client attribute between source and target, including PKCE settings and allowed scopes. Test sign-in and sign-out in each application before changing DNS or routing.

Sessions and refresh tokens invalidated at the wrong time

Switching identity providers can end active sessions and revoke refresh tokens at the moment users least expect it, often during business hours. Agree with application owners when sessions may end, and whether re-authentication is acceptable. Check token lifetimes and session idle settings in the target realm so they match the old service, not Keycloak defaults.

Duplicate accounts from federated identities

When users first sign in through a brokered identity provider after migration, Keycloak can create a second account if no existing user matches the external identity. Map each source account to its external identity before go-live, or define a first login flow that links accounts by a verified attribute. Review a sample of linked accounts for each identity provider after cutover.

Forgotten clients still pointing at the old service

Scheduled jobs, internal scripts, CI pipelines, mobile builds and legacy services often hold configuration that still points at the old identity service. Build a full inventory from gateway logs, secret stores and configuration repositories, not only from the application list. Keep the old service read-only for a defined period and watch its logs to find stragglers.

Upgrade 26.8 defaults that break migrated settings

The Keycloak 26.8 upgrade notes describe three defaults to review. Enforced SMTP StartTLS without plaintext fallback can break migrated mail settings for relays that do not offer TLS. Mandatory signature validation of backchannel logout tokens from external providers can reject logouts that previously succeeded. Persisting login failures to the database by default changes storage and may affect migrated event settings. Read the notes for your target version and test each one.

How the work changes by starting point

Moving from a hosted identity service is mostly an extraction problem. The vendor controls what can leave the platform, so the first task is finding out what your export can actually contain.

Export limits: Confirm whether user records, credentials, group memberships and client secrets can be exported, and in what format. Some services export users without passwords, which changes the migration to a staged sign-in or reset approach.
Hash handling: Identify the password hash algorithm, iteration count and salt format. Keycloak must verify these hashes at a user's first login, so test a sample of accounts before committing to a hash-based import.
Vendor-specific features: List custom claims, rules, pre-login actions and hosted MFA enrollments. Many have no direct equivalent and must be rebuilt as authentication flows, protocol mappers or extensions.
Client cutover: Map each application's redirect URIs, token settings and signing keys before cutover, since the issuer URL will change for every application.

What the client needs to provide

Scoping cannot close until the client provides read access to the source identity service and its configuration exports, plus an inventory of every application that signs in through it. For each application, record the redirect URIs, grant types, token and session settings, and sign-in methods. The inventory decides which clients move as they are and which need rework. Also provide the source's credential policy and the password hash algorithm, iteration count and salt format it can disclose, because those details decide whether existing hashes can be imported or whether users must reset passwords.

Name one accountable owner for each application and one person with authority over the cutover decision. Owners confirm sign-in behavior, test their own flows and sign off on go or no-go. Provide test users covering each role, group and federated login path that will migrate, and a non-production Keycloak target that matches the intended production layout. The production database must appear on Keycloak's supported list, which includes PostgreSQL 14 to 18. Confirm the exact engine and version your database team will run before scoping, because an unsupported choice changes the design.

Provide TLS certificates for the new hostname and the DNS plan that adds or moves it, including who controls the zone and how long existing records stay in place during the overlap. Agree a change window policy that states when cutover may happen, who may approve a change inside that window and when freezes apply. Rollback approval must be granted in advance: name who can reverse the cutover, the conditions that trigger a rollback, and the source service state that must remain available until the migration is accepted.

Keycloak does not define how a hosted or legacy identity service exports users, clients, roles or password hashes, so confirm these capabilities with the vendor of the source service before scoping closes. Ask whether user exports include password hashes, in what format, and whether client secrets are exported or must be reissued. Ask which tool version produces the export, what formats it supports and whether it limits record counts. If the source cannot disclose hashes, plan a forced reset path and prepare the users who will need to take it.

Common questions about Keycloak migration

How much does a Keycloak migration cost and what drives the price?

The cost follows from the written scope, so there is no standard price to quote in advance. Most of the effort comes from the number of realms and clients, the user count and directory sources, whether password hashes can be imported, custom authentication flows or extensions, and how many environments must be built and tested. These are mainly one-time project costs. Recurring costs include hosting, the production database, monitoring, and any upgrade or support retainer after go-live. Ask for the quote to itemize work by these drivers and to state which items are one-time and which recur.

How long does a Keycloak migration take, and how long should both systems run?

Duration depends mainly on the cutover approach. Moving everything in one window is simpler to plan but carries more risk than moving application by application. In side-by-side running, the old and new identity services both stay available, new clients point to Keycloak first, and users or applications move in groups while sign-in and logout are tested for each group. The overlap period depends on the client mix, how many applications are still waiting for cutover, and how much session and token behavior must be verified. Agree the length of that period and the exit criteria in the written scope.

Can password hashes move to Keycloak, and do users have to reset passwords?

Sometimes. Hashes can be carried over only when Keycloak accepts the source system's hash format and the export includes the hashes, so confirm both with the current provider and in a test realm before the plan is fixed. When hashes cannot be imported, the usual options are a forced password reset at first sign-in or a temporary fallback check against the old system during the overlap period. Either way, check MFA enrollments and active sessions too, because they may need re-enrollment or may not transfer with the user.

Can our own team run a Keycloak migration without an implementation partner?

Often yes, if the team already runs Keycloak or a similar identity service in production and has time to test properly. The hardest parts are usually password hash handling, cutting over clients without breaking token validation, keeping sessions and MFA intact during overlap, and proving that migrated realms behave the same under real sign-in traffic. Weigh those against engineering time and the risk of a failed cutover. A partner's role can be limited to one part, such as the hash migration or the test plan, so the decision is not all or nothing.

Do our applications need code changes when they move to Keycloak?

Usually not much. Most applications change configuration: client identifiers, secrets, redirect URIs, logout URLs and discovery endpoints. Some need code or library work, especially where the issuer URL changes, because the token's iss value and the expected audience must match what the application validates. Check signing key discovery, claim names for roles and groups, and any hard-coded hostnames. An early inventory of each application's OpenID Connect or SAML settings shows how much work the cutover contains.

What should our team provide to a partner for a Keycloak migration?

Name an accountable owner for the identity service and a decision maker who can approve cutover windows. Provide access to the current identity system's configuration, and an export of users, clients, roles and groups along with its hash settings. Supply a list of applications with owners, protocol type, redirect URIs and sign-in dependencies, plus test accounts for each environment. Application teams must be available for cutover testing and rollback decisions. Confirm in the written scope who owns each item and what access is needed to deliver it.

How DeployOpen scopes, delivers and hands over migrations

DeployOpen plans, implements, documents and supports self-hosted Keycloak inside your own infrastructure, including the move of users, clients and sign-in flows. Engagements are fixed-scope, and the scope is agreed in writing before work starts.

How we scope

Inventory users, clients, realms and sign-in flows on the source platform before any target design.
Confirm how each source stores password hashes and whether those hashes can move into Keycloak unchanged.
Agree the written scope, deliverables and cutover plan for Keycloak migration before work starts.

How we build

Build the target realms and clients in your infrastructure, with TLS and admin access separated from public endpoints.
Move users and password hashes in tested batches, then verify sample logins against each migrated client.
Plan both identity services side by side, sequencing client cutover one application at a time with defined rollback.

How we hand over

Document the realm model, client settings, mappers, flows and password hash handling as they were built.
Deliver a cutover runbook, a rollback procedure and a checklist of user and application verification steps.
Walk identity and application teams through operations, including the running Keycloak version and upgrade ownership.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after go-live.
Support can cover upgrade note review, realm testing before production and update approval for your Keycloak deployment.
Confirm support terms, response expectations and what is covered in writing before the migration begins.

Keycloak migration