Migration

Migrate from Keycloak

Idenplane follows similar concepts to Keycloak — realms, clients, roles, groups. Most migrations require just a realm export/import and URL change.

This guide walks through migrating from Keycloak to Idenplane — a lightweight, self-hosted Keycloak alternative. Because Idenplane implements the same standards (OAuth 2.0, OpenID Connect, and SAML 2.0) and mirrors Keycloak’s core concepts — realms, clients, roles, groups, and LDAP federation — most migrations come down to a realm export/import and a change of issuer URL in your applications. Keycloak password hashes (Argon2/BCrypt) can be preserved where supported, so many users never have to reset their passwords, and running both servers in parallel means there’s no hard cutover. New to the project? Start with Idenplane vs Keycloak.

Before you begin

Admin access to your Keycloak instance, to export the realm and users.
A host for Idenplane (Docker or Kubernetes) plus a PostgreSQL database.
The Idenplane admin API key (generated on first start), and optionally the CLI.
A staging environment so you can validate every flow before touching production.

Why migrate from Keycloak?

⚡

~150 MB

RAM vs Keycloak's 1 GB+

🛠

TypeScript

Modern stack vs Java/XML

📦

10 SDKs

vs Keycloak's limited client support

🎨

React 19

Admin UI vs Freemarker templates

Feature Mapping

Keycloak	Idenplane	Notes
Realm	Realm	Same concept — 1:1 mapping
Client (confidential)	Client (confidential)	Direct mapping, same config
Client (public)	Client (public)	Direct mapping, PKCE enforced
Realm Roles	Realm Roles	Same RBAC model
Client Roles	Client Roles	Same scoping
Groups	Groups	Hierarchical groups supported
User Federation (LDAP)	User Federation (LDAP)	Same sync options
Identity Providers	Identity Providers	OIDC/SAML brokering
Authentication Flows	Authentication Flows	Custom flow engine
Themes	Realm Theming	Per-realm login page themes
Events	Events / Audit Logs	Login + admin events
Client Scopes	Scopes	OAuth scopes with claims mapping

Step-by-Step Migration

Export Your Keycloak Realm

Use Keycloak's built-in export to create a JSON realm export file.

# Keycloak CLI export
bin/kc.sh export --dir /tmp/export --realm my-realm

# Or via Admin REST API
curl -X GET "https://keycloak.example.com/admin/realms/my-realm" \
  -H "Authorization: Bearer ${TOKEN}" > realm-export.json

Deploy Idenplane

Start a fresh Idenplane instance — it takes 30 seconds with Docker.

# Start Idenplane
docker compose up -d

# Verify it's running
curl http://localhost:3000/health

Import Realm to Idenplane

Use the Idenplane Admin API or CLI to import your Keycloak realm export.

# Using the Idenplane CLI's dedicated Keycloak importer
# (translates roles, groups, and identity providers — not a raw realm import)
idenplane migrate keycloak --file realm-export.json --dry-run
idenplane migrate keycloak --file realm-export.json

# Or via Admin API directly
curl -X POST "http://localhost:3000/admin/migration/keycloak" \
  -H "x-admin-api-key: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"data": '"$(cat realm-export.json)"'}'

Migrate Users

Idenplane supports user migration with password hash preservation where possible. For Keycloak Argon2/BCrypt hashes, users can log in without resetting passwords.

# Export users from Keycloak
curl -X GET "https://keycloak.example.com/admin/realms/my-realm/users" \
  -H "Authorization: Bearer ${TOKEN}" > users.json

# Import to Idenplane (with password hashes)
curl -X POST "http://localhost:3000/admin/realms/my-realm/users/import" \
  -H "x-admin-api-key: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @users.json

Update Client Applications

Update your applications to point to Idenplane. Since Idenplane implements the same OIDC/OAuth 2.0 endpoints, most apps only need a URL change.

# Keycloak (before)
OIDC_ISSUER=https://keycloak.example.com/realms/my-realm

# Idenplane (after) — same endpoint pattern!
OIDC_ISSUER=https://auth.example.com/realms/my-realm

# Discovery endpoint works the same way
curl https://auth.example.com/realms/my-realm/.well-known/openid-configuration

Verify & Cutover

Test authentication flows, verify token validation, and gradually shift traffic from Keycloak to Idenplane.

# Test login flow
idenplane user list --realm my-realm

# Test OIDC Discovery
curl https://auth.example.com/realms/my-realm/.well-known/openid-configuration

# Test token endpoint
curl -X POST https://auth.example.com/realms/my-realm/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=my-app" \
  -d "client_secret=my-secret"

Common questions

Will my users have to reset their passwords?

Usually not. Keycloak’s Argon2 and BCrypt password hashes can be imported, so users keep signing in with their existing credentials. Only unsupported hash formats require a reset.

Do my applications need code changes?

Rarely. Idenplane exposes the same OIDC discovery and token endpoints as Keycloak, so most apps only need the issuer URL updated. You can optionally adopt an official Idenplane SDK for a better developer experience.

How much downtime is involved?

None, if you run both servers in parallel. Migrate a non-critical client first, shift traffic gradually (10% → 50% → 100%), and keep Keycloak as a fallback until everything is validated.

Rollback Plan

Keep Keycloak running during migration. Use DNS or a reverse proxy to gradually shift traffic:

Run Idenplane alongside Keycloak (different port or hostname)
Migrate a non-critical client first to validate
Shift production traffic gradually (10% → 50% → 100%)
Keep Keycloak as fallback for 2 weeks after full cutover
Decommission Keycloak once fully validated