Keycloak migration guide: what to expect

Introduction: Why Migrate from Keycloak?

Keycloak is a powerful identity and access management solution, but for many organizations, it's not the best long-term fit. Whether you're looking to reduce dependency on a single vendor, improve performance, or integrate with other systems, migrating from Keycloak can be a strategic move.

For this guide, we're focusing on the practical steps to migrate from Keycloak to a self-hosted platform like Bastionary. Bastionary is a comprehensive platform that includes authentication, billing, licensing, and feature flags, making it an ideal choice for organizations looking to consolidate their systems.

Key Insight: Migrating from Keycloak is not just about moving data—it's about rethinking your architecture and ensuring a smooth transition.

Data Export: The First Step in Migration

Exporting Users, Roles, and Clients

Before you can migrate, you need to export all the data from Keycloak. This includes users, roles, clients, and realms. The export process is straightforward, but it's important to understand what you're exporting and how it will be used in the new system.

Here's a sample command to export users from Keycloak using the CLI:

keycloak-cli export-users --realm "my-realm" --format "json" --output "users.json"

Once you've exported the data, you'll need to import it into the new system. For Bastionary, this process is handled through the API, which allows for seamless integration.

Export Users: keycloak-cli export-users --realm "my-realm" --format "json" --output "users.json"
Export Roles: keycloak-cli export-roles --realm "my-realm" --format "json" --output "roles.json"
Export Clients: keycloak-cli export-clients --realm "my-realm" --format "json" --output "clients.json"

Realm Configuration: Ensuring Consistency

When migrating from Keycloak, it's important to ensure that the realm configuration is consistent across all systems. This includes settings like authentication providers, authorization policies, and client configurations.

For Bastionary, you can import the realm configuration using the API. Here's an example of how to do this:

curl -X POST "https://api.bastionary.com/v1/realm/config" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"realm": "my-realm", "config": "exported-config.json"}'

This ensures that the new system has the same configuration as the old one, reducing the risk of errors during migration.

Warning: Always verify the exported configuration before importing it into the new system.

Client Migration: A Critical Step

Client migration is one of the most critical steps in the Keycloak migration process. Clients are the entities that interact with the system, and their configuration must be accurately transferred to the new system.

For Bastionary, you can import clients using the API. Here's an example of how to do this:

curl -X POST "https://api.bastionary.com/v1/client/config" \
        -H