Back to Docs
Migration

Migrate from Keycloak

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

Why migrate from Keycloak?

⚡
~150 MB
RAM vs Keycloak's 1 GB+
🛠
TypeScript
Modern stack vs Java/XML
📦
7 SDKs
vs Keycloak's limited client support
🎨
React 19
Admin UI vs Freemarker templates

Feature Mapping

Keycloak AuthMe 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

1

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
2

Deploy AuthMe

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

# Start AuthMe
docker compose up -d

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

Import Realm to AuthMe

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

# Using AuthMe CLI
authme realm import --file realm-export.json

# Or via Admin API
curl -X POST "http://localhost:3000/admin/realms/import" \
  -H "x-admin-api-key: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d @realm-export.json
4

Migrate Users

AuthMe 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 AuthMe (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
5

Update Client Applications

Update your applications to point to AuthMe. Since AuthMe 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

# AuthMe (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
6

Verify & Cutover

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

# Test login flow
authme 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"

Rollback Plan

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

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