Migration to Descope

Migrating to Descope from another authentication provider or custom setup is a structured process, designed to allow you to retain security, functionality, and ease of use. This page covers migration options, supported third-party services, and password migration methods.

If you plan to move several apps or many customer tenants to production, start with the Migration Strategy. The strategy page describes the order of work, how to cut over one app at a time, and how to use an AI agent to write your export and import scripts.

Note

If you wish to layer Descope on top of your legacy provider instead of migrating fully away from it, you can also configure Descope as an identity provider in your legacy provider.

Migration Approaches

There are two primary strategies to migrate users and data to Descope:

  • Full Migration: Bulk-export users (and associated attributes/roles), import them into Descope, and then gradually switch traffic so Descope is the only source of truth. You can optionally add session migration so users with active sessions at your legacy provider do not have to sign in again.
  • JIT (Just-In-Time) Migration: Do not bulk-export users. Instead, provision users in Descope when they sign in, often by verifying their credentials or identity against the legacy provider (for example, via a generic HTTP connector or custom API) and then creating/updating the user in Descope on-the-fly.

Each individual migration guide (Auth0, Azure AD B2C, Cognito, etc.) explains how to implement these strategies for that specific provider, including when to combine JIT with full migration or session migration.

Supported Password Hashing Algorithms

Descope supports various hashing protocols to ensure smooth migration of passwords and minimal disruption for users. These protocols include:

  1. Bcrypt
  2. Argon2
  3. Django
  4. Firebase
  5. PBKDF2
  6. PHPass
  7. MD5 (for legacy compatibility)
  8. SHA-1, SHA2-256, SHA2-512, SHA3-256, and SHA3-512
  9. Buddy-Auth (bcrypt with SHA-512)

The Custom Data Store guide shows the hash format and parameters that Descope expects for each algorithm.

If your provider does not let you export password hashes, you can use JIT migration instead. Your sign-in Flow checks each password against the legacy provider, through a Generic HTTP connector, and creates the user in Descope on success. The Cognito and Azure AD B2C guides show this pattern step by step.

Migration Steps

Let an AI agent write your migration scripts

An AI agent connected to the Descope MCP Server can write the scripts that export your data and import it into Descope, mapped to your exact attributes, tenants, and roles. If you prefer not to use an agent, the Auth0, Cognito, Firebase, Ping, Shopify, and Custom Data Store guides link to open-source scripts that you can clone and run as templates.

1. Prepare User Data

  • Export data, ensuring you have all necessary fields such as unique identifiers (Login IDs), emails, names, and passwords.
  • Verify data accessibility to ensure smooth import using Descope's User Management API.

2. Create Users in Descope

  • Use Descope's Create User API or Batch Create User API to import your user data. This will create user records in Descope, including role assignments, attributes, and organization mappings as needed.

3. Import Passwords (Optional)

  • Descope supports various hashing algorithms, so users can log in with their existing passwords without needing a reset. For unsupported formats, consider a password reset flow or handle it via API updates.

4. Handle Social Logins and External Identity Providers (Optional)

  • For accounts with social logins (e.g., Google, Facebook), the migration will handle login IDs. Descope will link these IDs without needing further imports.

5. Import OAuth Clients (Optional)

Note

Importing a custom client ID changes your project's issuer to __BaseURL__/v1/apps/customized/__ProjectID__. See Migrating OAuth Clients for which services need the new issuer.

Migration Guides

Each guide below covers one provider or one part of a migration. The SSO and OAuth client guides apply to any source. Session migration supports Auth0 and Okta, and the rest of the guides are specific to a provider.

Was this helpful?

On this page