Migrating from Keycloak to Casdoor without losing your users

Moving an identity provider is mostly a user migration problem. Applications can be repointed in an afternoon; the users, their groups and their passwords are what make a cutover risky.

Casdoor ships a Keycloak syncer that reads Keycloak's own database and maps its schema into Casdoor users, which removes most of the manual work. This guide covers what it does, what it does not do, and how to plan the cutover.

What lives in Keycloak

A Keycloak realm stores more than a user table:

• Users in user_entity, with attributes in user_attribute.
• Credentials in credential, including the password hash, salt and iteration count.
• Groups in keycloak_group and memberships in user_group_membership.
• Clients, roles, flows, identity providers and themes, which are configuration rather than user data.

Casdoor's syncer handles the first three. The configuration has to be recreated.

The two migration paths

1. The Keycloak syncer (recommended)

The syncer extends Casdoor's database syncer with a preset mapping for Keycloak's schema, so you do not map columns by hand. It connects to the Keycloak database directly (MySQL or PostgreSQL), reads users and their credentials, and creates them in a Casdoor organization. See the Keycloak syncer docs.

Setup outline:

1. Create a read-only database user on the Keycloak database. Do not reuse Keycloak's own application user.
2. In Casdoor, open Syncers and create a new one with type Keycloak.
3. Fill in the database type (MySQL or PostgreSQL), host, port, database name and the read-only credentials.
4. Test the connection, then list and sync users. Start with a small group.
5. Set an auto-sync interval if you want Keycloak and Casdoor to stay in step during the transition.

2. Export and import

If you cannot open the Keycloak database to another system, export users through the Keycloak Admin REST API and import them into Casdoor as a spreadsheet. This path is more manual, and it does not carry password hashes, so every user needs a password reset or a first-login migration flow.

What happens to passwords

Keycloak stores passwords as salted PBKDF2-SHA256 hashes. Casdoor supports several credential schemes, including pbkdf2-salt, bcrypt and argon2id, and the Keycloak syncer copies the hash and salt from the credential table.

Whether existing passwords keep working depends on the parameters:

• Keycloak's default PBKDF2 parameters have changed across releases. Older defaults used 27,500 iterations and a 512-bit derived key, which matches Casdoor's pbkdf2-salt scheme.
• Newer Keycloak releases default to 600,000 iterations and a 256-bit key. A realm on those defaults will not verify against pbkdf2-salt as-is.
• If the realm uses a custom hashing provider, assume the hashes are incompatible.

Test this before the cutover: sync five test users, try to sign in with their real passwords, and see what happens. If they fail, plan a password reset campaign or a staged migration where each user sets a new password at first login. Do not discover this on cutover day.

What has to be rebuilt

The syncer moves people, not configuration. Budget time for:

• Applications (clients). Recreate each client in Casdoor with the same redirect URIs. Keep the old and new client IDs straight when you repoint applications.
• Roles and permissions. Casdoor has roles, permissions and Casbin-backed models; map Keycloak's realm and client roles onto them deliberately.
• Identity providers. Reconfigure Google, GitHub, Entra ID or SAML upstreams in Casdoor.
• Flows. Keycloak's authentication flows are not portable. Recreate the required steps (MFA, OTP, conditional access) with Casdoor's login and MFA settings.
• Themes and email templates. Branding has to be reapplied.
• Sessions. Nobody's session moves. Everyone signs in once after the cutover.

A cutover plan that can be rolled back

1. Stand up Casdoor next to Keycloak, with its own database.
2. Sync users and verify a sample, including password logins and group membership.
3. Recreate one low-risk application in Casdoor and point a test environment at it.
4. Run both systems in parallel. Keep Keycloak authoritative for passwords; use the syncer's interval to pick up new users and changes.
5. Move applications one at a time, starting with internal tools. Watch login error rates and support tickets.
6. Freeze Keycloak to read-only once all applications are on Casdoor. Keep it running for a few weeks as a rollback path.
7. Decommission after the rollback window, keeping a database backup.

The most common failure is moving everything in one night. Moving application by application keeps the blast radius small and gives you a working rollback at every step.

Why teams make the move

The usual reasons are licensing and operations: Keycloak is free software but expensive to operate at scale, and its upgrade cadence is demanding. Casdoor offers the same protocols (OIDC, SAML 2.0, CAS, SCIM, LDAP) with a smaller operational surface, and a managed option from $9 per month if you would rather not run it yourself.

For the wider comparison, see Keycloak alternatives and the Casdoor vs Keycloak page.

Casdoor is open source and self-hostable, with a hosted option from $9 per month and no per-user fees.