Migrate from Auth0

The WorkOS AuthKit API allows you to migrate your existing user data from a variety of existing sources. In this guide, we will walk through the steps to export, and then import your users, organizations, and enterprise SSO connections from Auth0.

Auth0 allows their customers to export user data using several tools, which are outlined in Auth0’s export documentation. A combination of exports may be necessary to retrieve all of the desired user information, including passwords.

The fastest way to export Auth0 data is with the WorkOS CLI migrations tool:

npx workos migrations export-auth0 \
  --domain my-tenant.us.auth0.com \
  --client-id <M2M_CLIENT_ID> \
  --client-secret <M2M_CLIENT_SECRET> \
  --package \
  --output-dir ./migration-auth0

This produces a migration package with users, organizations, memberships, roles, SSO handoff files, and warnings. You will need an Auth0 Machine-to-Machine application authorized for the Management API with the following scopes:

• read:users
• read:user_idp_tokens
• read:organizations
• read:organization_members
• read:organization_member_roles
• read:roles
• read:connections
• read:connections_options

For an interactive, step-by-step experience, use the wizard:

npx workos migrations wizard

The first tool is Auth0’s “Bulk User Export” jobs. These export jobs can be created programmatically using the Auth0 Management API, or through the official Auth0 “User Import / Export Extension”.

In both cases, an Auth0 customer can request which fields they’d like exported for each user, with the final output of the process being a newline-delimited JSON file.

If your Auth0 users currently sign-in using password-based authentication, and you’d like to import those passwords into WorkOS, then you will need to contact Auth0 support.

After opening a ticket with Auth0, it can take up to a week or more for your request to be processed. At the end you’ll be given another newline-delimited JSON file, containing a subset of user data such as ID, but more importantly the password hash.

If you used the CLI export with --package, you can merge the password hashes into the migration package:

npx workos migrations merge-passwords \
  --package ./migration-auth0 \
  --passwords auth0-passwords.ndjson

Once you’ve obtained the necessary export files, you can import your user data into WorkOS using the CLI or the API directly.

If you have webhook endpoints configured, temporarily disable delivery for the duration of the bulk import to avoid overwhelming your webhook consumers with high volumes of user.created, organization.created, and organization_membership.created events.

You can disable a webhook endpoint using the Update Webhook Endpoint API:

curl -X PATCH https://api.workos.com/webhook_endpoints/{id} \
  -H "Authorization: Bearer sk_example_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Re-enable the endpoint after the import is complete by setting status back to "enabled".

If you exported a migration package in the previous step, import it in one command:

npx workos migrations import-package ./migration-auth0

The orchestrator imports organizations, users, memberships, roles, and TOTP factors in the correct order. Preview what the import would do with --plan or --dry-run first.

For a standalone CSV import:

npx workos migrations import --csv users.csv

With the data from Auth0’s “Bulk User Export” job, you can use the WorkOS Create User API to import each of the users. Using the default fields from the Auth0 export, use the following mapping from Auth0 to parameters in your WorkOS Create User API calls:

If you also exported passwords from Auth0, you can import them during the user creation process, or later using the WorkOS Update User API.

Auth0 uses the bcrypt password hashing algorithm, which is supported by WorkOS. Make sure to pass the following parameters to the WorkOS API:

• The password_hash_type set to 'bcrypt'
• The password_hash set to the passwordHash field from your Auth0 export

If you have users who previously signed in through Auth0 using social auth providers, such as Google or Microsoft, those users can continue to sign in with those providers after you’ve migrated to WorkOS.

Check out our integrations page for guidance on configuring the relevant provider’s client credentials in WorkOS.

After your provider is configured in WorkOS, users can sign in with their provider credentials and will be automatically linked to a WorkOS user. WorkOS uses the email address from the social auth provider to determine this match.

Email verification behavior varies depending on whether the provider is known to verify email addresses. For example, users signing in using Google OAuth and a gmail.com email domain will not need to perform the extra verification step.

If your Auth0 tenant has enterprise SAML or OIDC connections, you can migrate them to WorkOS. The best strategy depends on how many connections you have.

Fewer than 15 connections – Admin Portal approach

For smaller deployments, the simplest path is to recreate each connection in WorkOS and coordinate with each customer’s IT team to update their Identity Provider configuration. You can use the Admin Portal to let customers self-service their SSO setup, reducing the coordination burden.

For each connection:

1. Create or identify the WorkOS organization matching the Auth0 organization
2. Create a SAML or OIDC connection in WorkOS
3. Share the Admin Portal link with the customer’s IT team so they can update their IdP configuration to point to WorkOS

15 or more connections – Transparent proxy migration

For larger deployments, coordinating with every customer’s IT team is impractical. Instead, you can perform a transparent migration where customer IdPs continue posting to the same Auth0 callback URL while a proxy routes the traffic to WorkOS. IT admins do not need to reconfigure anything on their end.

This approach requires that you have a custom domain configured in Auth0 (e.g., auth0.your-domain.com) so that you control the domain routing.

To migrate enterprise SSO connections with zero friction, the following must be true:

• You have configured a custom domain with Auth0 so that you control the domain routing
• Your SAML enterprise connections do not use SAML Request Signing with Auth0 tenant global key pairs
• Your SAML enterprise connections do not use SAML Response Encryption with Auth0 tenant global key pairs

The WorkOS migrations CLI can export your Auth0 enterprise connections:

npx workos migrations export-auth0 \
  --domain my-tenant.us.auth0.com \
  --client-id <M2M_CLIENT_ID> \
  --client-secret <M2M_CLIENT_SECRET> \
  --package \
  --entities sso \
  --output-dir ./migration-auth0-sso

This produces files with SAML and OIDC connection details, custom attribute mappings, and proxy routes. Contact support@workos.com with the export files, and the WorkOS team will import the connections for you.

After the import, WorkOS provides a mapping between Auth0 and WorkOS connection IDs that you can use during the gradual rollout.

Once connections are imported into WorkOS, configure a proxy in front of your Auth0 custom domain to route IdP callback traffic to WorkOS. The proxy intercepts callbacks at your Auth0 custom domain’s /login/callback path and redirects them to your WorkOS custom domain.

The proxy flow works as follows:

1. A user authenticates with their IdP, which posts the SAML response or OIDC callback to your Auth0 custom domain
2. The proxy redirects the callback to WorkOS
3. If WorkOS finds a matching imported connection, it processes the response and redirects to your application’s WorkOS callback
4. If WorkOS cannot match the connection, it redirects back with a fallback=auth0 query parameter, and the proxy forwards the original callback to Auth0

This fallback mechanism ensures zero downtime – connections that haven’t been migrated yet continue to work through Auth0.

The proxy can be implemented using Cloudflare redirect and transform rules, a Cloudflare Worker, or any reverse proxy you control. The workos-migrations repository includes a reference implementation. For Cloudflare rules configuration, see the detailed migration guide.

Once the proxy is in place, you can opt-in connections to WorkOS one at a time. WorkOS Feature Flags can control which organizations use WorkOS SSO versus Auth0 during the migration. Create a feature flag (e.g., workos-sso-enabled) and target it to specific organizations as you migrate them.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS();
const featureFlags = workos.featureFlags.createRuntimeClient();
await featureFlags.waitUntilReady({ timeoutMs: 5000 });

function getSSOAuthorizationUrl(organizationId: string): string {
  const useWorkOS = featureFlags.isEnabled('workos-sso-enabled', {
    organizationId,
  });

  if (useWorkOS) {
    return workos.userManagement.getAuthorizationUrl({
      provider: 'authkit',
      organizationId,
      clientId: process.env.WORKOS_CLIENT_ID!,
      redirectUri: process.env.WORKOS_REDIRECT_URI!,
    });
  }

  // Fall back to Auth0 for organizations not yet migrated
  return (
    `https://${process.env.AUTH0_DOMAIN}/authorize?` +
    `client_id=${process.env.AUTH0_CLIENT_ID}` +
    `&redirect_uri=${process.env.AUTH0_REDIRECT_URI}` +
    `&response_type=code` +
    `&organization=${organizationId}`
  );
}

This lets you gradually migrate organizations to WorkOS SSO, verify each one works correctly, and roll back individual organizations if needed – all without code deployments.

After the migration is complete, you can turn off your Auth0 tenant entirely. You will need to maintain the custom domain in your DNS provider so that the proxy continues to route any remaining traffic.

Auth0 has a concept of “Organizations” which are analogous to WorkOS Organizations, in that both represent a B2B customer.

If you used the CLI with --package, organizations are imported automatically by import-package. Otherwise, you can use the Auth0 Management API to programmatically paginate through each Organization, then call the WorkOS Create Organization API to create matching Organizations in WorkOS.

You can export Auth0 organization memberships using Auth0’s “Bulk User Export” as described in the Exporting Auth0 user data step, and then use the WorkOS Organization Membership API to add each user to their respective organization.

There are some differences between the Multi-Factor Auth (MFA) strategies offered by Auth0 and WorkOS.

Auth0 supports SMS-based second factors, however WorkOS does not due to known security issues with SMS. Users who have SMS-based second factors will need to switch to using email-based Magic Auth, or re-enroll in MFA using a TOTP-based authenticator instead.

If your Auth0 users have TOTP factors, the CLI can enroll them in WorkOS after import:

npx workos migrations enroll-totp \
  --input totp-secrets.csv \
  --totp-issuer "YourApp"

If your application allows users to sign up at any time, you should consider the timing of your migration. Users who sign up after you’ve exported data from Auth0 but before you’ve switched to WorkOS for authentication will be omitted from the migration.

There are two main strategies to handle this:

Schedule an appropriate time for the migration and temporarily disable signup functionality. This can be controlled using a feature flag in your application. After the migration is complete and your application is using WorkOS for authentication, re-enable signups.

For applications that cannot disable signups, implement a “dual-write” strategy. When a new user signs up, create records in both Auth0 and WorkOS using the Create User API. This keeps WorkOS synchronized with new users, though you’ll still need to perform the historical user migration. Be aware that you’ll need to keep user updates (email changes, password changes) synchronized between both systems until the migration is complete.

After completing your migration to WorkOS, you can take advantage of additional features:

• Audit Logs: Track security-relevant events across your application
• Radar: Protect against bots, fraud, and abuse
• Feature Flags: Control feature rollout for specific users and organizations

If you haven’t already, check out the AuthKit Quick Start guide to learn how to integrate WorkOS into your application.

For questions or assistance with your migration, contact support@workos.com.