Migrate from Keycloak to a Managed CIAM: A 90-Day Playbook

Self-hosted Keycloak is a strong CIAM choice, until the operations cost or feature gap drives the team toward managed. Common 2026 reasons: SRE burden of running clustered Keycloak, slow native passkey UX, B2B Org-level features that lag managed competitors, or organizational shift to vendor-supported infrastructure. This playbook covers the 90-day migration to any major managed CIAM. The pattern is similar across Auth0, Microsoft Entra External ID, and Stytch; the playbook calls out vendor specifics where they matter.

Phase 1, Discovery and target CIAM mapping (14 days)

Keycloak's flexibility is its biggest migration challenge. Custom themes, custom authenticators, custom SPI implementations, realm-specific authentication flows, every customization needs a migration path or an explicit deprecation. The first two weeks are inventory plus mapping each Keycloak feature to a target CIAM equivalent.

Realm inventory. How many realms? Per-realm: client list, role model, identity providers, authentication flows, custom themes, event listeners, custom user attributes. The realm count typically maps to "Organizations" or "tenants" in the target CIAM.

Client inventory. Every client (OIDC or SAML) integrated with Keycloak. For each: protocol, redirect URIs, scopes, custom mappers, signing algorithms. Each becomes an application in the target CIAM.

Custom code inventory. Custom authenticators, user storage SPIs, event listeners, theme customizations, REST extensions. Each needs a migration plan: replace with managed equivalent, re-implement as webhook, or deprecate.

Federated identity inventory. External IdPs Keycloak federates with, Google, Facebook, GitHub, SAML federation with enterprise IdPs. The bindings need to be re-established on the target CIAM.

Target CIAM mapping. For each Keycloak concept, identify the target equivalent:

• Realm → Organization / Tenant
• Client → Application
• Role → Role / Permission
• Group → Group / Team
• Authentication flow → Auth flow / Action / Hook
• Custom authenticator → Webhook / Action / Pre-token-generation hook
• Theme → Customization / Branded login

Where the target CIAM lacks a Keycloak feature, document the workaround or deprecation.

Phase 2, User and credential export (14 days)

Keycloak provides clean export options that make this phase easier than typical migrations.

User export. Keycloak's kc.sh export exports realm data including users, with optional inclusion of credentials. The export is JSON; the structure is well-documented.

Password hash export. Keycloak supports password-hash export, the credentials array in the user export contains hash type (typically PBKDF2-SHA256 or argon2) plus parameters. Most managed CIAM (Auth0, MojoAuth, Stytch) support PBKDF2 and argon2 hash import; the migration can preserve hashes without forcing a reset.

Hash algorithm verification. Confirm the target CIAM supports the specific hash format. PBKDF2-SHA256 with Keycloak's iteration counts is widely supported; argon2id is also well-supported. Custom hash configurations may require a JIT verification fallback.

MFA export. TOTP secrets and WebAuthn credentials are in the user export. Most managed CIAM support import of TOTP secrets directly; WebAuthn credentials are more vendor-specific, many require re-enrollment.

Bulk import to target. Use the target CIAM's bulk import API. Auth0's "import job", Microsoft Entra's bulk import, Stytch's import API all accept user records with hashes. Verify a small batch first; iterate on field mapping issues; then run the full import.

Phase 3, Realm-to-tenant configuration mapping (14 days)

Configuration is where Keycloak migrations usually have the most surprises. Custom authentication flows, custom mappers, and realm-specific overrides all need explicit re-implementation.

Realm config to Org config. Each Keycloak realm becomes a tenant / Org / project on the target. Configure: branding (custom theme to managed branding), email templates, password policy (or replacement with passkey-first defaults), session timeouts, MFA requirements.

Client config to Application config. Each Keycloak client becomes an Application on the target CIAM. Configure: protocol (OIDC/SAML), redirect URIs, scopes, audience, signing algorithm. For SAML clients, regenerate the SP metadata; for OIDC clients, capture the new issuer and JWKS URLs.

Identity provider migration. External IdPs (Google, Facebook, SAML) reconfigured on the target. The provider client IDs/secrets carry over; the redirect URIs change to the target CIAM's callback URL. Each provider needs its admin console updated with the new redirect URI.

Authentication flow migration. Keycloak's flexible authentication flows often don't map 1:1 to target CIAM. Common patterns:

• Required password + required TOTP → managed adaptive MFA
• Conditional MFA based on group → CIAM rule / action
• Custom authenticator (e.g., risk score) → CIAM webhook / action

Document each flow's intent and re-implement against the target's primitives.

Phase 4, Application code migration (28 days)

The longest phase. Every application that integrated with Keycloak needs a code update.

OIDC client config. Update each app's OIDC config: issuer URL, JWKS URL, audience, scopes. The OIDC standard means the app code mostly doesn't change, just the configuration.

SAML client config. Update each app's SAML config: IdP metadata URL, SP entity ID (may change), assertion consumer service URL. Re-import SP metadata at the target CIAM.

Token validation. Update JWT validation to use the target's JWKS. If the app uses Keycloak-specific claims (realm_access, resource_access), map to the target's claim structure (https://customer.com/roles, permissions, etc.).

Keycloak-specific SDK removal. If apps use keycloak-js, keycloak-spring-security, or other Keycloak-specific SDKs, replace with the target's SDK or generic OIDC client. Generic OIDC clients (oauth4webapi, oidc-client-ts, openid-connect-spring-boot) are recommended over vendor-specific SDKs to reduce future migration cost.

Backend services. Service-to-service tokens (M2M client credentials) need re-issuing on the target. Update each backend service's client ID/secret.

Logout flows. Front-channel and back-channel logout endpoints change. Update each app's logout configuration.

Phase 5, Cutover and Keycloak decommission (20 days)

With users imported, configuration mapped, and code migrated, execute the cutover.

DNS / load balancer cutover. Point the auth subdomain (auth.customer.com or similar) at the target CIAM. Existing Keycloak sessions become invalid; users hit the new login screen.

Staged or bigbang. For low-risk environments, bigbang cutover at a low-traffic window. For higher-risk, stage by application: migrate one app at a time over 1-2 weeks, observing each before proceeding.

Active session handling. Existing Keycloak sessions can continue until tokens expire (typically minutes to hours). New sessions go through the target CIAM. Some teams force-invalidate Keycloak sessions for a faster transition.

Monitoring. Sign-in success rate, MFA challenge rate, token validation error rate across all apps. Two-week observation window before declaring the migration complete.

Keycloak decommission. After two weeks of clean operation:

• Quiesce Keycloak (read-only mode)
• Snapshot the Keycloak database for archive
• Stop Keycloak instances
• Decommission the Keycloak infrastructure (Kubernetes deployments, RDS instances, load balancers)
• Cancel monitoring alerts and on-call rotations specific to Keycloak

Post-migration retrospective. Document what went well, what surprised the team, and what the target CIAM lacks that Keycloak provided. Often the modernization opportunity (passkeys, adaptive auth, embedded admin portals for B2B) becomes the next quarter's roadmap.

Anti-patterns to avoid

• Underestimating custom code surface. Custom authenticators, SPIs, and event listeners often have undocumented business logic. Audit thoroughly.
• Big-bang cutover without staging. A surprise in any of the migrated applications becomes a customer-facing outage; stage where possible.
• Skipping the federated rebinding plan. Users discover Google/SAML federation broken post-cutover; reconfigure each provider's redirect URIs ahead of time.
• No fallback path. A documented rollback is essential, even if the rollback is "DNS revert + targeted hotfix," it needs to be ready before cutover.
• Forgetting service-to-service tokens. Backend services with M2M client credentials are easy to overlook and cause silent failures post-cutover.

What success looks like at day 90

• Target CIAM is the primary auth. All applications, users, federations operate against the new platform.
• Keycloak decommissioned or running in read-only archive mode.
• Operational burden reduced. Engineering hours previously spent on Keycloak ops redirect to product work.
• Modernization adopted. Most migrations seize the moment to add passkeys, adaptive auth, or B2B Organization-level features that managed CIAM ship natively.
• Documented runbook for the new operational model, vendor escalation paths, support contracts, monitoring dashboards.

For build-vs-buy framing, see the build vs buy CIAM guide. For the modernization opportunities at cutover, see the passkey rollout playbook.