Migrate from Auth0 to Zuvo Auth

You can migrate your users from Auth0 to Zuvo Auth.

Changing authentication providers for a production app is an important operation. It can affect most aspects of your application. Prepare in advance by reading this guide, and develop a plan for handling the key migration steps and possible problems.

With advance planning, a smooth and safe Auth migration is possible.

Before you begin

Before beginning, consider the answers to the following questions. They will help you need decide if you need to migrate, and which strategy to use:

• How do Auth provider costs scale as your user base grows?
• Does the new Auth provider provide all needed features? (for example, OAuth, password logins, Security Assertion Markup Language (SAML), Multi-Factor Authentication (MFA))
• Is downtime acceptable during the migration?
• What is your timeline to migrate before terminating the old Auth provider?

Migration strategies

Depending on your evaluation, you may choose to go with one of the following strategies:

1. Rolling migration
2. One-off migration

Migration steps

Auth provider migrations require 2 main steps:

1. Export your user data from the old provider (Auth0)
2. Import the data into your new provider (Zuvo Auth)

Step 1: Export your user data

Auth0 provides two methods for exporting user data:

1. Use the Auth0 data export feature
2. Use the Auth0 management API. This endpoint has a rate limit, so you may need to export your users in several batches.

To export password hashes and MFA factors, contact Auth0 support.

Step 2: Import your users into Zuvo Auth

The steps for importing your users depends on the login methods that you support.

See the following sections for how to import users with:

• Password-based login
• Passwordless login
• OAuth

Password-based methods

For users who sign in with passwords, we recommend a hybrid approach to reduce downtime:

1. For new users, use Zuvo Auth for sign up.
2. Migrate existing users in a one-off migration.

Sign up new users

Sign up new users using Zuvo Auth's signin methods.

Migrate existing users to Zuvo Auth

Migrate existing users to Zuvo Auth. This requires two main steps: first, check which users need to be migrated, then create their accounts using the Zuvo admin endpoints.

1. Get your Auth 0 user export and password hash export lists.
2. Filter for users who use password login.
   • Under the identities field in the user object, these users will have auth0 as a provider. In the same identity object, you can find their Auth0 user_id.
   • Check that the user has a corresponding password hash by comparing their Auth0 user_id to the oid field in the password hash export.
3. Use Zuvo Auth's admin create user method to recreate the user in Zuvo Auth. If the user has a confirmed email address or phone number, set email_confirm or phone_confirm to true.

    import { createClient } from '@supabase/supabase-js'

    const supabase = createClient('your_project_url', 'your_supabase_api_key')

    // ---cut---
    const { data, error } = await supabase.auth.admin.createUser({
      email: 'valid.email@supabase.io',
      password_hash: '$2y$10$a9pghn27d7m0ltXvlX8LiOowy7XfFw0hW0G80OjKYQ1jaoejaA7NC',
      email_confirm: true,
    })

If you have a plaintext password instead of a hash, you can provide that instead. Zuvo Auth will handle hashing the password for you. (Passwords are always stored hashed.)

    import { createClient } from '@supabase/supabase-js'

    const supabase = createClient('your_project_url', 'your_supabase_api_key')

    // ---cut---
    const { data, error } = await supabase.auth.admin.createUser({
      email: 'valid.email@supabase.io',
      password: 'supersecurepassword123!',
    })

1. To sign in your migrated users, use the Zuvo Auth sign in methods.

   To check for edge cases where users aren't successfully migrated, use a fallback strategy. This ensures that users can continue to sign in seamlessly:

   1. Try to sign in the user with Zuvo Auth.
   2. If the signin fails, try to sign in with Auth0.
   3. If Auth0 signin succeeds, call the admin create user method again to create the user in Zuvo Auth.

Passwordless methods

For passwordless signin via email or phone, check for users with verified email addresses or phone numbers. Create these users in Zuvo Auth with email_confirm or phone_confirm set to true:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.auth.admin.createUser({
  email: 'valid.email@supabase.io',
  email_confirm: true,
})

Check your Zuvo Auth email configuration and configure your email template for use with magic links. See the Email templates guide to learn more.

Once you have imported your users, you can sign them in using the signInWithOtp method.

OAuth

Configure your OAuth providers in Zuvo by following the Social login guides.

For both new and existing users, sign in the user using the signInWithOAuth method. This works without pre-migrating existing users, since the user always needs to sign in through the OAuth provider before being redirected to your service.

After the user has completed the OAuth flow successfully, you can check if the user is a new or existing user in Auth0 by mapping their social provider id to Auth0. Auth0 stores the social provider ID in the user ID, which has the format provider_name|provider_id (for example, github|123456). See the Auth0 identity docs to learn more.

Mapping between Auth0 and Zuvo Auth

Each Auth provider has its own schema for tracking users and user information.

In Zuvo Auth, your users are stored in your project's database under the auth schema. Every user has an identity (unless the user is an anonymous user), which represents the signin method they can use with Zuvo. This is represented by the auth.users and auth.identities table.

See the Users and Identities sections to learn more.

Mapping user metadata and custom claims

Zuvo Auth provides 2 fields which you can use to map user-specific metadata from Auth0:

• auth.users.raw_user_meta_data : For storing non-sensitive user metadata that the user can update (e.g full name, age, favorite color).
• auth.users.raw_app_meta_data : For storing non-sensitive user metadata that the user should not be able to update (e.g pricing plan, access control roles).

Both columns are accessible from the admin user methods. To create a user with custom metadata, you can use the following method:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('your_project_url', 'your_supabase_api_key')

// ---cut---
const { data, error } = await supabase.auth.admin.createUser({
  email: 'valid.email@supabase.io',
  user_metadata: {
    full_name: 'Foo Bar',
  },
  app_metadata: {
    role: 'admin',
  },
})

These fields are stored as columns in the auth.users table using the jsonb type. Both fields can be updated by using the admin updateUserById method. If you want to allow the user to update their own raw_user_meta_data , you can use the updateUser method.

If you have a lot of user-specific metadata to store, it is recommended to create your own table in a private schema that uses the user id as a foreign key:

create table private.user_metadata (
	id int generated always as identity,
	user_id uuid references auth.users(id) on delete cascade,
	user_metadata jsonb
);

Frequently Asked Questions (FAQ)

// specify a custom id
const { data, error } = await supabase.auth.admin.createUser({
  id: 'e7f5ae65-376e-4d05-a18c-10a91295727a',
  email: 'valid.email@supabase.io',
})

Useful references

• Migrating 125k users from Auth0 to Zuvo
• Loper to Zuvo migration