Migrate from Keycloak

This guide covers migrating from Keycloak to Wocha using a realm export file or the Keycloak Admin API.

Prerequisites

Concept mapping

Data mapping

Step 1 — Export realm data

Option A: Realm export file

In the Keycloak Admin Console:

1. Select your realm
2. Realm settings → Action → Partial export
3. Export users, groups, roles, and identity providers
4. Save as realm-export.json

Option B: Live Admin API

Obtain an admin access token:

TOKEN=$(curl -s -X POST "https://auth.example.com/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=admin" \
  -d "password=YOUR_PASSWORD" \
  -d "grant_type=password" | jq -r .access_token)

The CLI prompts for base URL, realm, and token when you select live import.

Step 2 — Dry run

export WOCHA_MANAGEMENT_API_KEY=wocha_mgmt_...
export WOCHA_TENANT=your-tenant
 
wocha migrate keycloak --dry-run

The plan summarises:

• Users, groups (organisations), roles, and identity providers
• Users missing email addresses
• Identity providers requiring OAuth credential configuration

Step 3 — Import users

wocha migrate keycloak

Groups map to Wocha organisations; roles map to member/admin assignments. Identity providers are listed for manual configuration.

Step 4 — Configure identity providers

Keycloak identity providers map to Wocha connections:

Add OAuth client credentials in Connections → Social or SAML metadata in Connections → Enterprise.

Handling passwords

Keycloak realm exports do not include password hashes by default (security restriction). Options:

1. Magic link re-registration — wocha.users.sendRecovery(userId) after import
2. Export with credentials — Keycloak can export password credentials if explicitly enabled (not recommended for production exports)
3. Migration flow — implement a custom login page that validates against Keycloak on first login, then creates the Wocha session
4. SSO/federated — configure identity providers in Wocha before cutover

Step 5 — Map applications (clients)

Keycloak clients map to Wocha applications:

import { WochaClient } from "@wocha/sdk";
 
const wocha = new WochaClient({ tenant: process.env.WOCHA_TENANT!, apiKey: process.env.WOCHA_API_KEY! });
 
await wocha.applications.create({
  client_name: keycloakClient.clientId,
  grant_types: ["authorization_code"],
  redirect_uris: keycloakClient.redirectUris,
});

Step 6 — Validate migration

wocha migrate keycloak --validate

Checks user counts, organisation alignment, and identity provider configuration.

Post-migration checklist

• All users imported
• Groups mapped to organisations with correct membership
• Identity providers configured in Wocha
• Applications (clients) recreated with correct redirect URIs
• Recovery emails sent to password-based users
• Application middleware updated to Wocha SDK
• Keycloak realm kept active during validation period

Rollback considerations

• Keycloak realm export is read-only — import does not modify Keycloak
• User metadata preserves keycloak_id and realm name
• Multi-realm deployments may need one Wocha tenant per realm
• SAML/OIDC metadata changes require IdP and SP configuration updates at cutover