Migrate from Keycloak to Zitadel

The documented Keycloak path is designed to keep existing passwords usable. You export the realm's users with kc.sh export, convert them with the zitadel-tools migration utility, which keeps PBKDF2 password hashes usable, and import the result through POST /admin/v1/import. For most users, this means sign-in works with the password they already know, without a reset campaign. The word "most" matters here. Whether a given account carries over depends on how your realm stores its hashes and which credentials each user holds. Treat the documented path as a hypothesis to test in your environment before anyone promises users that their passwords will carry over.

Start with the password policy in your realm. Record the hash algorithm and the hash iteration count, because these settings shape the exported credential data. Confirm that the algorithm is a PBKDF2 variant the converter supports, and check the iteration handling against the Zitadel migration documentation for the version you plan to run. Then export a small set of test users, convert them, and import them into a non-production Zitadel instance. Sign in with each test account and record the result. If any realm, client or user group uses a different algorithm or a changed iteration value, note it now, because that group needs its own plan before cutover.

Passwords are only one credential type. List every second factor and passwordless method enrolled in the realm, including OTP applications, WebAuthn security keys and any passkeys, and count how many users hold each one. The documented conversion covers password hashes, so do not assume that OTP secrets or WebAuthn registrations will arrive in Zitadel in the same form. Test each credential type with a sample user. Where a type does not carry over, those users will need to enroll again. Zitadel's passkey support includes password login as a fallback, which can ease the step for users who lose a device, but re-enrollment still has to be scheduled and communicated.

Decide the path for users whose credentials cannot be carried over during the design phase, and name the owner of that decision. A forced reset imports the account and requires a new password at first sign-in. It needs a notification channel that reaches users who are not currently signed in, and a help desk prepared for a rise in recovery requests. A just-in-time fallback checks the old credential at sign-in and migrates the account when the check succeeds. It keeps the source system running and reachable for as long as accounts still depend on it, so it needs a defined end date. Confirm the current just-in-time steps in Zitadel's migration guide before you choose, and write the chosen rule into the cutover plan.

A Keycloak realm usually becomes a Zitadel organization inside an instance, and the instance itself is chosen first because it is the isolation boundary. Zitadel treats an instance as a virtual tenant with full data isolation, while organizations hold the projects and users. If customers need separate data stores, separate administrators or separate configuration, give each group its own instance. If they only need separate user populations under one operator, several organizations in one instance may be enough. Confirm this decision with the security and operations owners before any import, because moving a customer between instances later is a migration in its own right. Keycloak clients then map to Zitadel applications inside projects, and each project groups its applications, roles and grants.

Roles need the most careful inventory. Keycloak realm roles are visible to every client in the realm, while client roles belong to one client and can share names with roles in other clients. Export the role list for each realm and each client, then decide which realm roles and client roles become project roles and which become grants that assign those roles to users or groups in a given organization. Composite roles, which bundle other roles in Keycloak, usually need to be flattened into explicit grants so that each permission is visible in Zitadel. Role names that collide across clients need a prefix or a namespace in the project. Ask the application owners to confirm which roles their code checks, because a renamed role is a silent authorization change.

The project boundary is a design decision with lasting consequences. One project per product suits a shared application that serves many customers with the same role catalog, since roles are defined once and granted per organization. One project per customer suits customers who need different role catalogs or who must be administered separately, at the cost of more projects to maintain and more duplicated applications. Many teams settle on a hybrid, with a shared project for common products and dedicated projects for customers with unusual role models. Write the rule down before mapping begins, and test it with one product and two customers, so that the pattern is proven before it is repeated across the estate.

Redirect URIs, client secrets and token claims are rebuilt for each application and then tested, not copied. Redirect URIs must match exactly across development, staging and production, so list each one from the Keycloak client configuration and confirm it against the application's own settings. Generate new client secrets in Zitadel and plan the rotation in every relying party, because a secret is not something to carry across unchanged without a checked cutover. Keycloak protocol mappers that add roles, groups or custom attributes to tokens must be recreated as Zitadel claim behavior, then verified by decoding real tokens for each application. Brokered logins need their own mapping: each customer organization can use a different identity provider, so link each external identity provider to the correct organization and confirm which provider each customer uses.

The first decision is which Keycloak version the export will come from. Compare the version in use with the current release, 26.8.1, published October 13, 2026, and read the upgrading guide for every release between your version and the one you export from. Since Keycloak 26.0, the project plans four minor releases a year, and breaking changes in a minor release are opt-in, so a version that was current a year ago may need configuration review before you export. If you run the Red Hat build of Keycloak, check its own support lifecycle as well. Red Hat's product page showed 26.6 as its latest version, so the supported build may trail the upstream release. Record the exact version reported by the running server, not the version in a deployment manifest, which may be out of date.

Next, identify the production database and its exact version. Keycloak supports MariaDB, Microsoft SQL Server, MySQL, Oracle Database, PostgreSQL 14 to 18, EnterpriseDB Advanced, Amazon Aurora PostgreSQL and Azure SQL. The default file database is for development only, so finding it in production is a finding to resolve before the export starts. Also confirm how schema changes are applied. Keycloak migrates its schema automatically at startup by default, but administrators can apply the SQL themselves, which the upgrading guide suggests for large deployments. Confirm which mode you run and whether any migration is pending, because an export taken during an unfinished migration can capture a state you did not intend. Record the number of realms and users so the export and import can be sized and checked later.

Document the high availability design as it runs today. Keycloak describes three architectures: a single cluster, optionally spread across availability zones, a multi-cluster deployment (v2) that does not use an external Infinispan cluster, and the deprecated multi-cluster v1 design that runs a separate Infinispan cluster per site. Both supported designs require a synchronously replicated database. Write down which design you run, where the database replicas sit, and how failover behaves. This matters for the export because the export reads from the live database, and the restore point must reflect a consistent state. If you run v1, treat the move to a supported design as a separate workstream, since v1 is deprecated, and plan it before the migration window rather than during it.

If Keycloak runs under the Keycloak Operator, confirm how the operator is installed and which custom resources manage the deployment. The operator is installed through Operator Lifecycle Manager (the recommended method), with kubectl, or with an experimental Helm chart. It manages Keycloak, KeycloakRealmImport, KeycloakOIDCClient and KeycloakSAMLClient resources. Check whether operator updates use manual approval. The operator documentation strongly recommends manual approval to avoid unintended automatic upgrades. If updates are automatic, an operator upgrade could change the running Keycloak version during your window. Switch to manual approval before the window and name the person who approves changes. Also check whether realm and client configuration lives in these custom resources, because the operator can reapply that state after you have changed it outside the cluster.

Take the export in a controlled window, with a restore point taken immediately before it. Freeze administrative changes and realm edits for the duration, and confirm who can authorize a rollback. Test the restore procedure on a copy of the database before relying on it. The Zitadel Keycloak guide uses kc.sh export, and the conversion step depends on the format that export produces, so the team must confirm the exact export procedure, options and handling of password hashes with the Keycloak documentation and the Zitadel documentation for the versions in use. Ask the Zitadel side to confirm which export format the zitadel-tools utility expects for your Keycloak version. Where those documents differ from your environment, resolve the difference in writing before the window opens.