Migration Strategy
A migration to Descope moves four things: your data (tenants, SSO connections, roles, users, and applications), your passwords, your login experience, and the traffic from each of your apps. This page describes the order that gets larger organizations to production fastest, and the decisions you make at each stage.
This page is for teams that plan a production migration across several apps or many customer tenants. If you want the exact export and import steps for one provider, go to that provider's guide from the migration overview.
Match First, Then Enhance
The fastest migrations start with a Descope setup that behaves exactly like your current auth. Users sign in with the same methods, see the same screens, and land in the same tenant with the same roles. New features such as passkeys, adaptive MFA, or a redesigned login page come after the cutover.
A 1:1 match gives you a simple test for every app: does the app behave the same as before? When the answer is yes for every login path, the app is ready to move. When you change the experience during the migration, a failed test can come from the migration or from the new feature, and the two are hard to separate.
After every app runs on Descope, you can improve the experience one change at a time, with the old behavior as a known baseline.
Choose Your Path
Your current setup decides which steps apply to you. Most organizations fit one of three shapes, and many have a mix of them.
- Homegrown auth: You own the user store, so you can export all of your users, tenants, roles, and SSO connections. You import them into Descope, and then move each app to Descope.
- A hosted provider with embedded login: Your apps call a provider such as Auth0, Cognito, or Firebase through its SDK. You import your data, rebuild the login screens as Flows, and then replace the provider's SDK with the Descope SDK in each app.
- A hosted provider with federated apps: Your apps connect to a provider such as Okta Customer Identity, Auth0, or PingOne over OIDC or SAML. Descope can act as an identity broker between your apps and that provider, which lets you move one app at a time.
If your customers sign in through their own identity providers (IdPs), such as Okta Workforce or Microsoft Entra ID, you also need SSO migration. SSO migration lets those customers keep their current IdP configuration, so their IT teams do not have to change anything.
In every case, you migrate apps one at a time rather than all at once. A per-app cutover keeps each change small, makes each test clear, and limits the effect of a problem to one app.
Step 1: Plan the Mapping
Before you import anything, decide how each object in your current system maps to Descope. For example, an Auth0 Organization becomes a Descope tenant, and an Auth0 Action usually becomes a step in a Flow. The mapping also tells you which data you can export, and which data you must rebuild.
You have three ways to produce the mapping:
- With an AI agent: The Descope Skills include migration skills for Auth0, Okta Customer Identity, Stytch, PingOne, and WorkOS. With the Descope MCP Server connected, a skill reads your code and your current configuration and writes a migration plan for you to review before it changes any code. For a homegrown system or a provider without a skill, the agent can still read your configuration through the MCP server and explain how each piece maps to Descope.
- With Descope Support: The Descope team can review your current setup and help you plan the migration. Contact Descope Support to start.
- On your own: If your team already knows identity well, you can use the provider guides on this site to configure Descope directly.
Step 2: Import Your Data
Import your data in dependency order, because each object can refer to objects that come before it. A user can belong to a tenant and hold roles, and an application can refer to users. If you import users first, their tenant and role assignments have nothing to point to.
The fastest way to move your data is to let an AI agent write the migration scripts for you. An agent connected to the Descope MCP Server can write a script that exports your data from your current provider or homegrown database. The agent then maps the export to Descope and writes the import scripts, which you review and run with a Management Key.
An agent writes the script for your exact data, including custom attributes and edge cases that a generic tool does not know about. Scripts are easy to rerun, so you can import a test batch into a development project first.
If you prefer not to use an AI agent, Descope publishes open-source migration scripts for several providers, such as the Descope migration tool for Auth0, Cognito, Firebase, and Ping. You can clone these scripts and run them as they are, or use them as templates for your own scripts. The Auth0, Cognito, Firebase, Ping, Shopify, and Custom Data Store guides link to their scripts.
Use this order:
- Tenants: Create one tenant for each customer organization.
- SSO connections: Add each customer's SAML or OIDC settings to its tenant. See SSO migration for how to keep the customer's current IdP configuration.
- Roles and permissions: Recreate your roles and permissions, or your ReBAC schema if you use fine-grained authorization.
- Resources: Create a Resource for each API that your current provider issues tokens for, with the same audience and scopes. See Machine-to-Machine Clients and APIs.
- Users: Import users with their tenant memberships, roles, and custom attributes through the User Management API.
- Applications: Recreate federated apps, and import OAuth clients with their existing client IDs and secrets.
Login Identifiers
Users keep signing in with the same identifier they use today. Descope stores one or more login IDs for each user, and a login ID can be an email address, a phone number, or a username. You import the current login IDs with each user, and you can associate several login IDs with the same user.
OTP and magic links send codes and links to the user's email address or phone number, so they depend on a verified contact. When you import a user, you would set verifiedEmail and verifiedPhone to match the verification state in your current system. Never mark an unverified email or phone as verified, because anyone who controls that address could then sign in as the user with OTP or a magic link.
Users with a verified email or phone could later move to passwordless sign-in with OTP or magic links. Passwordless sign-in is easier to introduce after every app runs on Descope, so during the migration you would keep each user on the method they use today.
Passwords do not depend on a verified contact. A password can belong to any login ID, including a username with no email or phone behind it. If your users sign in with a username today, you can import the username as a login ID, and those users keep signing in with their password.
If your current system never verified email addresses or phone numbers, OTP and magic links are not available to your users at first. Users who sign in with a password today typically stay on passwords, and the password strategy in the next section decides whether users keep their current passwords.
Passwords
Your password strategy depends on whether your current provider lets you export password hashes.
If you can export the hashes, import them with the users. Descope supports common hash formats, so users keep their current passwords and do not see a reset. The migration overview lists the supported algorithms.
If you cannot export the hashes, use just-in-time (JIT) migration. Your sign-in Flow validates the password with your legacy provider, such as Okta, Entra ID, or Cognito, through a Generic HTTP connector.
If the password is correct, the Flow creates the user in Descope with that password. The user signs in as usual and never notices the migration.
Each user migrates on their next sign-in, so users who never sign in stay behind.
Plan a date to import the remaining users without passwords, send them a password reset or passwordless sign-in, and turn off the legacy provider.
If you can neither export the hashes nor run JIT migration against your current provider, your users cannot bring their passwords to Descope. In that case, you must make sure that every user can reset their password. You can keep your existing password reset mechanism, or your Descope Flow can handle the reset with the Send Password Reset action.
Users who sign in with only a username
Descope sends password reset emails through Magic Link, so the Send Password Reset action needs an email address on the user. A user with a verified phone number but no email can still reset in a Flow. The Flow signs the user in with OTP over SMS, and then runs the Update Password action to set the new password.
A user who signs in with only a username has no email or phone for Descope to reach. For those users, you would rely on your existing reset mechanism, or an admin can set a new password for the user in the Console.
Passkeys and Authenticator Apps
Passwords are not the only credentials your users hold. Passkeys and authenticator app (TOTP) seeds each behave differently in a migration.
- Passkeys: A passkey belongs to the domain where the user registered it. You can migrate passkeys only if your current provider lets you export them. Descope's passkey top-level domain must also match the domain from registration. Contact Descope Support to import exported passkeys.
- Authenticator apps: If your current provider exports TOTP seeds, you can import them with the users. Users then keep using their existing authenticator app.
What you can export depends on the provider. Auth0 exports password hashes and MFA secrets through a support request, as a PGP-encrypted file.
| Provider | Password hashes | Passkeys | TOTP seeds |
|---|---|---|---|
| Auth0 | Yes | Yes | Yes |
| AWS Cognito | No | No | No |
| Okta CIS | No | No | No |
| Azure AD B2C | No | No | No |
| Frontegg | No | No | No |
When a credential cannot move, users re-enroll it in Descope. A common pattern is to mark imported users with a freshlyMigrated attribute. Your sign-in Flow then prompts those users to register a new passkey or authenticator app after their first sign-in.
Machine-to-Machine Clients and APIs
Users are not the only callers of your APIs. Backend services, scheduled jobs, and partner integrations often authenticate as machine-to-machine (M2M) clients, for example an Auth0 M2M application that uses the client_credentials grant. These clients hold a client ID and secret from your current provider, and your APIs validate the tokens that the provider issues to them.
In Descope, the client becomes a confidential Inbound App, and the API it calls becomes a Resource. The Resource defines the API's audience (aud) and scopes, and Policies decide which scopes each client receives.
Resources matter most for M2M clients. A client_credentials token has no user and no consent screen behind it, so the Resource's scopes are the only limit on what the client can do.
To move your M2M clients, you can follow these steps:
Create a Resource for each API
Create an API Resource for each API your current provider protects, such as the APIs in your Auth0 tenant. Use the same audience and scope names, so your APIs keep accepting the same claims, for both M2M and user tokens.
Import each client with its existing credentials
Create an Inbound App for each client, and pass its current clientId and clientSecret. The client keeps calling with the same credentials. See Migrating OAuth Clients.
Associate the clients with their Resources
Associate each Inbound App with the Resources it calls. Then add Policies that grant each client only the scopes it had before.
Update the issuer in your APIs
Point each API's token validation at the Descope issuer. Importing a custom client ID changes the issuer, as described in Issuer After Importing Client IDs.
When Your Current System Has No Resources
Some systems never used OAuth for service calls. Services may share a static API key, or call internal APIs that never validate an audience or scopes. In that case, you have nothing to match 1:1, and Resources become a design decision instead of a migration step.
Descope recommends that you treat Resources as a follow-up for these systems. Migrate your users and apps first, and keep your current service authentication unchanged during the cutover. If a service needs a Descope-issued token right away, a Descope Access Key is the closest match to a static API key.
After the migration, you can define a Resource for each internal API and move each service to an Inbound App with the client_credentials grant. With that change, every service token carries an audience and scopes that your APIs can validate. Each service gets only the access you grant it, instead of a shared key with full access.
Configuration and Settings
Your current provider also holds configuration that controls how users sign in, such as password rules and session lifetimes. If you import only the data, users can notice the difference on their first sign-in. To keep a 1:1 match, you can export these settings from your current provider and recreate them in Descope.
You would recreate each setting as it is today, even a setting you plan to change. A stricter password policy or a shorter token lifetime is easier to roll out after every app runs on Descope, when the old behavior gives you a known baseline.
Where your provider keeps these settings depends on the provider. In Azure AD B2C, for example, these settings are usually defined per policy, in each user flow or custom policy. You would then go through each policy and decide where each of its settings belongs in Descope.
Authentication Method Settings
Start with the settings of each authentication method, such as your password policy. In Descope, you set the password policy for the whole project. You can also override the policy for a tenant when a customer organization has its own rules today.
In Okta, password policies are often tied to groups. If each group matches a customer organization, you can recreate the group's policy as a tenant override. If a group maps to a Descope role instead, you can contact Descope Support to set a password policy on that role. Otherwise, you can set the policy for the whole project.
OTP and magic links follow the same pattern. Each has project settings, and a tenant can override them. Settings for other methods, such as passkeys and authenticator apps, apply to the whole project.
Session Settings
Move session settings after you import users and applications, because session settings can be different for each app. With the apps in Descope, you can compare the session lifetime of each app in your current provider with its new setup in Descope.
Descope sets token lifetimes for the whole project in session management. A tenant can override the session settings. An OIDC app or a Custom app can also override the session settings for the tokens it receives. An Inbound App can set its own access and refresh token expiration.
Email Templates and Branding
Your current provider sends emails for verification, password resets, and invitations, and each email has its own template. You can recreate each email as a messaging template in Descope, with the same content, so users keep receiving emails they recognize.
Branding works the same way. You can add your logo, colors, and fonts to a style in Descope. If your apps use different branding today, you can apply styles per application. Your Flows then use these styles when you rebuild the login experience in the next step.
Connectors
Your current provider may also send data to other services, such as your email provider or your logging system. In Descope, these integrations are connectors, and you configure some of them at the project level before any app moves.
Two kinds of connectors belong in this project-level setup:
- Email and SMS connectors: Your authentication methods send codes and links through a messaging connector. You select the connector in each method's settings, so users get messages from the same provider as before.
- Audit connectors: An audit webhook or another audit and troubleshooting connector streams audit events to your own systems. You can add one before the cutover, so your logs and alerts have no gap.
Other integrations take effect only as steps in the Flow you build. A fraud detection service or a custom webhook you call today still starts as a connector on the Connectors page. You then add that connector as a step in the Flow, instead of selecting it in a project setting. A custom webhook usually becomes a Generic HTTP connector step. See Connectors in Flows for how to add each step.
Fraud protection works in a similar way. Some risk signals, such as bot detection and the risk score, need the Fingerprint Assess action in your Flow. Other signals, such as impossible travel and trusted devices, do not need a Flow step.
Step 3: Rebuild the Login Experience
Descope recommends Flows for your login experience, because you can change a Flow's logic and screens without a code deploy.
You can build each Flow in the Console, or ask an AI agent connected to the Descope MCP Server to rebuild your current login. The agent can also apply your styles and set up widgets, such as the User Profile Widget, to replace your app's account pages.
Each app can run a Flow in a few ways. A web app can embed the Flow in its own pages, and a mobile app can run it as a native Flow. An app can also connect to Descope over OIDC or SAML as a federated app. Wherever the Flow runs, a step in it sends each user to the right place.
While a hosted provider such as Okta or Cognito still holds your customers' SSO connections, the Flow sends those customers to that provider. You add the provider to Descope as an OIDC or SAML connection, and it signs each user in through the customer's existing connection. All other users sign in with Descope Flows directly.
After SSO migration, Descope federates directly to each customer's IdP, and you can turn off the legacy provider.
Your apps connect only to Descope, through an embedded Flow, a native Flow, or a federated app over OIDC or SAML. Wherever the Flow runs, a step in it decides where each user signs in. Customers whose SSO connections live in a hosted provider, such as Okta or Cognito, still sign in through that provider. All other users sign in with Descope Flows.
Your apps talk only to Descope through both stages, so they don't need another change. You can move users and SSO customers off the legacy provider at your own pace by editing the Flow's logic and configuration.
What you do next depends on how each app connects to your auth today.
Embedded Login
If an app shows the login screens inside its own pages, make sure the new Flow matches the current login experience screen for screen. Then replace the old login component with the Descope Flow component in that app. The SDK guides show how to add a Flow to each framework.
Federated Apps
If an app connects to your current provider over OIDC or SAML, Descope can act as an identity broker. In a broker setup, Descope sits between your apps and your legacy provider. You connect each app to Descope as a federated app, and the app signs users in through the same Flow as your embedded apps.
Step 4: Cut Over to Production
Before you cut over any app, make sure your automated tests can sign in through Descope. See Get Automated Tests Running First.
How you cut over depends on who controls the hostname that your customers' IdPs send SSO responses to. Each customer configured that hostname in their SAML or OIDC connection, so the hostname decides how much you can change without asking customers to change anything.
If You Manage Your Own Auth Hostname
With homegrown auth, you usually own the hostname in your customers' IdP configuration, such as login.example.com. You don't need the two-phase cutover in the next section, because there is no hosted provider to federate to.
When your apps are ready on Descope, you redirect that hostname's SSO traffic to Descope, and Descope routes each SSO response to the correct tenant. Your customers' IdPs keep sending responses to the ACS URL they already have, such as https://login.example.com/saml. Descope doesn't serve that path, so a CNAME record alone breaks SSO at cutover. The redirect worker in the SSO migration guide receives those requests and sends them on to Descope.
If a Hosted Provider Holds Your Connections
If your apps and customer connections live in a provider such as Auth0, Okta Customer Identity, PingOne, or WorkOS, that provider serves the hostname your customers configured.
In this case, you move in two phases. First, route every app through Descope while Descope federates to the provider. Then, move the existing hostname to Descope.
Your apps and your customers' IdPs both use login.example.com, which points at the legacy provider. That hostname is in every customer's SAML or OIDC settings, so it is the part that has to move last.
Phase 1: Route All Apps Through Descope
In the first phase, every app starts to use Descope, either through embedded Flows or as a Federated App. The legacy provider stays in place and still holds the customer connections.
- Create a new hostname for Descope: Set up a new custom domain for Descope, such as
auth.example.com. Keep the existing hostname on the legacy provider for now. - Federate to the legacy provider: Add the legacy provider to Descope as an OIDC or SAML connection. Use a Flow action to send SSO users to the provider, which signs them in through the customer's existing connection.
- Move each app to Descope: Move one app at a time to the new hostname. Test each app on Descope before you move the next one.
At the end of Phase 1, all sign-in traffic flows through Descope. Your apps no longer talk to the legacy provider directly, so the next phase changes nothing in your apps.
Phase 2: Move the Existing Hostname
Once every app runs on Descope, you redirect the existing hostname, such as login.example.com, to Descope. Customer IdPs keep sending SSO responses to that hostname, so SSO migration can take over each connection without most customers changing their SAML or OIDC settings. The exceptions are customers whose IdP validates your SP certificate and customers who configured the provider's own domain, described below.
When the hostname points to Descope, you can stop federating to the legacy provider and turn it off.
The existing hostname must be one you control
Phase 2 works only if your customers configured a custom domain that you own, such as login.example.com. If a customer configured the provider's own domain, such as your-tenant.auth0.com, you cannot point that hostname to Descope. Those customers must update their connection, which they can do themselves with the SSO Setup Suite.
A two-phase cutover lets you test every app on its own and move gradually, with very little downtime. If a problem appears in Phase 1, it affects only the app you just moved.
Customer IdPs That Validate Your SP Certificate
Both cutover paths rely on customer IdPs accepting SAML requests that Descope signs. Most IdPs accept them, because they don't validate the signature on the request. Some IdPs do validate it against your previous provider's certificate, and Keycloak is the most common one. Customers on those IdPs need to update their SAML configuration to point to Descope before you move them.
You can find these customers before you change any DNS record. A short script can start SAML SSO through Descope for each tenant and report whether the customer's IdP accepts the request. Checking Which IdPs Validate Your SP Certificate includes the script and explains how to read its results. Plan the outreach to those customers early, since they cut over only after their admins update the connection.
Sessions
Users with an active session when an app moves do not have to sign in again if you add session migration. With session migration, your app sends the legacy Auth0 or Okta token to Descope, and Descope exchanges it for a Descope session.
Session migration can also create users. In just-in-time mode, Descope creates a user who is not in Descope yet from the provider's profile. For an Okta or Auth0 migration, session migration can then replace part of the bulk import for users with an active session at cutover.
Test Each App Before It Moves
Because each app moves on its own, you can test each one against the same list before it goes to production. Use a separate environment for testing, and test users for automated tests.
Get Automated Tests Running First
Make sure your automated test suites can sign in through Descope before you migrate your first app. When many apps move in sequence, a test suite that cannot authenticate blocks every app behind it. Migrations commonly stall at this step, because the accounts that tests use are often not part of the main user import.
Before the first cutover, go through every account that your tests and pipelines use to sign in:
- Service accounts: If your tests or CI pipelines call your APIs as an M2M client, import that client as an Inbound App with its existing client ID and secret. Associate the Inbound App with the same Resources as in production. See Migrating OAuth Clients.
- Passwordless test users: For end-to-end tests that sign in through OTP, magic links, or enchanted links, create test users in Descope. Your tests can generate codes and link tokens for test users through the API, so Descope sends no email or SMS.
- Automation users with passwords: If a test signs in with a password, that user must already exist in Descope with the password. You can import the user with their password hash, or make sure your JIT migration Flow can migrate them on the first test run. Otherwise, the first automated sign-in fails.
Run the full test suite against Descope in your test environment and resolve any failures before you start the cutover. With the tests in place, each later app only needs its own app-specific tests.
Checklist for Each App
For each app, test that:
- Every sign-in method from the old setup works, including password, social login, MFA, and SSO.
- Users land in the correct tenant with the correct roles and permissions.
- Tokens contain the claims that the app and its APIs expect.
- Sign-out, password reset, and account recovery work.
- Any federated or OAuth clients receive tokens from the new issuer.
When an app passes every item, move it to production and start on the next app. Before the final cutover, go through the production checklist.
Browser-Saved Passwords
Imported password hashes keep each password valid in Descope, but the browser side of the password is a separate concern. Browsers and password managers save a password for the domain where the user typed it.
If your sign-in page moves to a new hostname, such as auth.example.com instead of login.example.com, the saved password no longer fills in automatically. Users can still sign in, but they have to find the saved entry or type the password. Embedded Flows that run on your app's own pages keep the same domain, so autofill keeps working there.
Next Steps
Migration Overview
Find the import guide for your current provider, and the list of supported password hash formats.
SSO and SCIM Migration
Move customer SSO and SCIM connections to Descope without changes on the customer side.
Descope Skills
Install the migration skills that let an AI agent map your current setup and plan the migration.
Federated Apps
Connect your OIDC and SAML apps to Descope as the identity provider or identity broker.