Keycloak Migration Guide

This guide provides step-by-step instructions for a successful migration from Keycloak to Descope.

There are two main paths to migrate Keycloak users to Descope:

• Full Migration - You completely migrate your users and identity providers from Keycloak into Descope and retire Keycloak.
• Just-in-Time (JIT) Provisioning - You progressively migrate users into Descope as they log in. Descope verifies their existing Keycloak password via Keycloak's API, then creates their user record locally.

Keycloak vs. Descope Terminology

Keycloak and Descope use similar identity concepts, but they differ in how user isolation works.

In short: Keycloak Realms are effectively Projects and Keycloak Groups/Organizations are Tenants.

Exporting Users from Keycloak

You can export users either via the Admin REST API or directly from the Keycloak database.

Export via REST API

kcadm.sh get users -r <realm_name> -o > keycloak_users.json
 
This will output JSON records with usernames, emails, and attributes.
 
#### b. Export via Database Access (Optional)
 
If you have DB access (PostgreSQL or MySQL):
 
```sql
select FIRST_NAME, LAST_NAME, EMAIL, USERNAME, EMAIL_VERIFIED, U.ID as ID, 
C.SECRET_DATA::jsonb ->> 'value' as PASSWORD,
C.SECRET_DATA::jsonb ->> 'salt' as SALT,
C.CREDENTIAL_DATA::jsonb ->> 'hashIterations' as HASHITERATIONS,
C.CREDENTIAL_DATA::jsonb ->> 'algorithm' as ALGORITHM,
CREATED_TIMESTAMP, REALM_ID
from USER_ENTITY U, CREDENTIAL C
where U.ID = C.USER_ID AND U.REALM_ID = 'RealmID'

Export the result as CSV or JSON for easier transformation.

Importing Users into Descope

Use the Descope Management API or Batch Create Users API to import users.

Example import payload:

{
  "users": [
    {
      "loginIds": ["alice"],
      "email": "alice@example.com",
      "name": "Alice Johnson",
      "roleNames": ["admin"],
      "userTenants": ["acme-corp"],
      "customAttributes": {
        "source": "keycloak",
        "department": "engineering"
      },
      "hashedPassword": {
        "pbkdf2": {
          "hash": "base64string",
          "salt": "base64string",
          "iterations": 27500,
          "type": "sha256"
        }
      }
    }
  ]
}

Password Migration

Keycloak's default password hashing algorithm is PBKDF2-SHA256 (≈ 27,500 iterations).

You can confirm the algorithm from the CREDENTIAL table or export file.

Descope supports a variety of password hashing algorithms. You can see the full list of supported algorithms here.

If you export the hash, salt, and iterations, you can import passwords so users don't need to reset them.

Otherwise, you'll need to trigger a password reset for the user through Descope Flows post-migration.

Migrating Roles and Tenants

Keycloak Roles map directly to Descope Roles, and Groups or organizations in Keycloak should become Tenants in Descope.

It's worth noting that users in Descope can belong to multiple tenants at the same time.

"userTenants": ["engineering", "marketing"]

Migrating Identity Providers

If your realm has connected IdPs (e.g., Google, GitHub, Azure AD):

• OIDC IdPs → Recreate as Custom OAuth Providers or Tenant OIDC SSO Connections
• SAML IdPs → Recreate as Tenant SAML SSO Connections

Specifically with OIDC, reusing client IDs, secrets, and redirect URIs ensures seamless continuity. You'll have to add the Descope Redirect URI to the IdP's list of authorized callback URLs, but other than that, you should be able to reuse the same IdP configuration.

Whether you use a Custom OAuth Provider or a Tenant OIDC SSO Connection, is dependent on whether or not all users or just specific Keycloak users (such as part of a group or organization) should be able to use the IdP to login to Descope. Tenant SSO connections are usually reserved for a specific group of users that exist as/within a Descope Tenant.

With SAML, if you do not want to have to re-configure your IdP to use the Descope SSO URL and Entity ID, you can refer to our SSO Migration Guide for more information.

Just-in-Time (JIT) Provisioning Migration with Password Validation

This method allows Descope to create users dynamically as they log in — validating their credentials through Keycloak in real-time.

This is ideal when you don't have access to password hashes, but still want a smooth, password-based transition.

How It Works

1. A user enters their email/username and password in a Descope Flow.

2. Descope calls your backend webhook.

3. Your backend sends a POST request to Keycloak's token endpoint for that realm:

   POST https://<keycloak-domain>/realms/<realm>/protocol/openid-connect/token
   Content-Type: application/x-www-form-urlencoded
    
   grant_type=password
   client_id=<direct-grant-client>
   client_secret=<client-secret-if-required>
   username=<user>
   password=<password>

4. If Keycloak responds 200 OK, the credentials are valid.

5. Descope creates a user in your project using the Management API with the same password.

6. The user is now fully migrated and can authenticate directly through Descope going forward.

Requirements

• Direct Access Grants (a.k.a. Resource Owner Password Credentials flow) must be enabled for your Keycloak client.
• Keycloak must be reachable by your backend.

Security and Limitations

• The password grant flow is deprecated for public clients — only use this for temporary migration.
• Protect your client credentials and restrict access to this endpoint.
• Disable the direct-grant flow once all users have migrated.

Integration Flow Example

Below is an example flow for migrating users JIT with password validation:

1. User submits credentials.
2. Descope Flow triggers your Generic HTTP Connector POST request to Keycloak's token endpoint.
3. Keycloak will validate the credentials and return a token if successful, with any additional user attributes as well.
4. On success, Descope will invoke the Sign Up / Password action and create a new user with pre-existing password. We can also set custom attributes for the user here if we want.
5. After the migration, future logins for this user will happen directly with Descope, not invoking the connector anymore.

Transitioning Away from Keycloak

After the majority of users have logged in once (and thus migrated):

• Disable the Keycloak connection.
• Switch your apps to use Descope SDKs directly.
• Remove the password grant configuration in Keycloak.

Post-Migration: Handling Freshly Migrated Users

A common strategy when migrating users from Keycloak to Descope is to set a custom attribute on migrated users to track their migration status and customize their first login experience. This approach works for both full migration and JIT migration scenarios.

Setting the Migration Attribute

For Full Migration: When you import users using the Management SDK or API, include a custom attribute like freshlyMigrated: true in the user payload:

{
  "loginIds": ["alice"],
  "email": "alice@example.com",
  "customAttributes": {
    "freshlyMigrated": "true",
    "source": "keycloak"
  }
}

For JIT Migration: In your migration flow, after successfully validating credentials with Keycloak and creating the user, use the Update User / Attributes action to set the freshlyMigrated attribute to true.

Customizing Behavior for Migrated Users

Once the attribute is set, you can use conditional logic in your Descope flows to provide a tailored onboarding experience for users who just transitioned from Keycloak.

For example, you can:

• Prompt for MFA enrollment
• Ask users to verify or update their email/phone
• Request password reset (if passwords weren't migrated)
• Show a welcome message explaining the migration

Clearing the Migration Flag

Once the user completes the onboarding flow, use the Update User / Attributes action to set freshlyMigrated to false. This ensures they won't see the migration prompts on subsequent logins.