Migrate from Auth0

The WorkOS User Management 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 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 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.

Once you’ve obtained the necessary export files, you have two options for importing your user data into WorkOS.

WorkOS has a public GitHub repository containing code that can be run to import users into WorkOS using the data retrieved in the previous step.

If you’d rather write your own code, the same process can be completed using the public WorkOS APIs, as described below.

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:

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.

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

If you’d like to export your Auth0 organizations, you can use the Auth0 Management API to programmatically paginate through each Organization. You can 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.

With your users now imported, you can now start using WorkOS to manage your Auth0 users. If you haven’t, take a look at our Quick Start guide to learn how to integrate WorkOS User Management into your application.