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:
- Bcrypt
- Argon2
- Django
- Firebase
- PBKDF2
- PHPass
- MD5 (for legacy compatibility)
- SHA-1, SHA2-256, SHA2-512, SHA3-256, and SHA3-512
- 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)
- If partner apps or M2M services already authenticate with a
client_idandclient_secret, create matching Inbound Apps and import those credentials on create. The clients can keep calling with the same ID and secret while you cut the token endpoint over to Descope. - Create a Resource for each API those clients call, with the same audience and scopes, so your APIs keep validating the same claims. See Machine-to-Machine Clients and APIs.
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.
SSO and SCIM
Move customer SSO and SCIM connections to Descope without changes in the customer's IdP
Sessions
Keep users signed in by exchanging legacy session tokens for Descope sessions
OAuth Clients
Import existing OAuth client IDs and secrets so partner and M2M clients keep working
Auth0
Learn how to migrate your Auth0 users, organizations, permissions, and roles to Descope
Okta CIS
Learn how to migrate your Okta Customer Identity Solution (CIS) users to Descope
Azure AD B2C
Learn how to migrate your Azure AD B2C users to Descope
AWS Cognito
Learn how to migrate your Cognito user groups and custom attributes to Descope
Firebase
Learn how to migrate your Firebase users to Descope
Ping
Learn how to migrate your Ping users, environments, permissions, and roles to Descope
Keycloak
Learn how to migrate your Keycloak users, realms, and identity providers to Descope
Stytch
Learn how to migrate your Stytch users, organizations, SDKs, sessions, and M2M clients to Descope.
Frontegg
Learn how to migrate your Frontegg users, accounts, roles, and SSO connections to Descope
Clerk
Learn how to migrate your Clerk users, organizations, roles, and sessions to Descope
Shopify
Learn how to migrate your Shopify customers to Descope
Custom Data Store
Learn how to migrate your users from a custom data store to Descope