从 Auth0 迁移到 Supabase Auth

你可以把你的用户从 Auth0 迁移到 Supabase Auth。

🌐 You can migrate your users from Auth0 to Supabase 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.

通过提前规划，Auth 的迁移可以顺利且安全。

🌐 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:

• 随着用户数量增长，认证提供商的费用会如何变化？
• 新的身份验证提供商提供所有需要的功能吗？（例如，OAuth、密码登录、安全断言标记语言(SAML)、多因素认证(MFA)）
• 迁移过程中可以有停机时间吗？
• 你打算在终止旧的认证提供商之前什么时候迁移？

迁移策略 #

🌐 Migration strategies

根据你的评估，你可以选择以下几种策略之一：

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

1. 滚动迁移
2. 一次性迁移

迁移步骤 #

🌐 Migration steps

身份认证提供商迁移需要两个主要步骤：

🌐 Auth provider migrations require 2 main steps:

1. 从旧服务提供商（Auth0）导出你的用户数据
2. 把数据导入到你新的提供商（Supabase Auth）

第1步：导出你的用户数据 #

🌐 Step 1: Export your user data

Auth0 提供了两种导出用户数据的方法：

🌐 Auth0 provides two methods for exporting user data:

1. 使用 Auth0 数据导出功能
2. 使用 Auth0 管理 API。这个端点有速率限制，所以你可能需要分几批导出用户。

要导出密码哈希和多因素认证信息，请联系 Auth0 支持。

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

步骤 2：将你的用户导入 Supabase Auth #

🌐 Step 2: Import your users into Supabase 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:

• 基于密码的登录
• 无密码登录
• OAuth

基于密码的方法 #

🌐 Password-based methods

对于使用密码登录的用户，我们建议采用混合方法来减少停机时间：

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

1. 新用户可以用 Supabase Auth 注册。
2. 一次性迁移现有用户。

注册新用户 [#sign-up-new-users]

🌐 Sign up new users

使用 Supabase Auth 的 登录方法 注册新用户。

🌐 Sign up new users using Supabase Auth's signin methods.

把现有用户迁移到 Supabase 认证 [#migrate-existing-users-to-supabase-auth]

🌐 Migrate existing users to Supabase Auth

将现有用户迁移到 Supabase Auth。这需要两个主要步骤：首先，检查哪些用户需要迁移，然后使用 Supabase 管理端点创建他们的账户。

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

1. 获取你的 Auth 0 用户导出和密码哈希导出列表。

2. 筛选使用密码登录的用户。

   • 在用户对象的 identities 字段下，这些用户的提供者会是 auth0。在同一个身份对象中，你可以找到他们的 Auth0 user_id。
   • 通过将用户的 Auth0 user_id 与密码哈希导出中的 oid 字段进行比较，检查用户是否有相应的密码哈希。

3. 使用 Supabase Auth 的 admin create user 方法在 Supabase Auth 中重新创建用户。如果用户有已确认的电子邮件地址或电话号码，请将 email_confirm 或 phone_confirm 设置为 true。

   1
   import { createClient } from '@supabase/supabase-js'
   2
   3
   const supabase = createClient('your_project_url', 'your_supabase_api_key')
   4
   5
   // ---cut---
   6
   const { data, error } = await supabase.auth.admin.createUser({
   7
     email: 'valid.email@supabase.io',
   8
     password_hash: '$2y$10$a9pghn27d7m0ltXvlX8LiOowy7XfFw0hW0G80OjKYQ1jaoejaA7NC',
   9
     email_confirm: true,
   10
   })

   支持的密码哈希算法

   Supabase 支持 bcrypt 和 Argon2 密码哈希。

   如果你有明文密码而不是哈希值，你也可以提供明文密码。Supabase Auth 会帮你处理密码的哈希。（密码总是以哈希形式存储的。）

   1
   import { createClient } from '@supabase/supabase-js'
   2
   3
   const supabase = createClient('your_project_url', 'your_supabase_api_key')
   4
   5
   // ---cut---
   6
   const { data, error } = await supabase.auth.admin.createUser({
   7
     email: 'valid.email@supabase.io',
   8
     password: 'supersecurepassword123!',
   9
   })

4. 要让你的已迁移用户登录，请使用 Supabase Auth 的登录方法。

   为了检查用户未成功迁移的边缘情况，可以使用备用策略。这可以确保用户继续无缝登录：

   1. 尝试用 Supabase Auth 登录用户。
   2. 如果登录失败，试着用 Auth0 登录。
   3. 如果 Auth0 登录成功，再次调用管理员创建用户方法，在 Supabase Auth 中创建用户。

无密码方法 #

🌐 Passwordless methods

要通过邮箱或手机号进行无密码登录，请查找已验证邮箱地址或手机号的用户。使用 email_confirm 或 phone_confirm 设置为 true，在 Supabase Auth 中创建这些用户：

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

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('your_project_url', 'your_supabase_api_key')
4
5
// ---cut---
6
const { data, error } = await supabase.auth.admin.createUser({
7
  email: 'valid.email@supabase.io',
8
  email_confirm: true,
9
})

检查你的 Supabase Auth 邮箱配置 并配置你的 邮箱模板 以使用魔法链接。查看 邮箱模板指南 了解更多。

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

一旦你导入了用户，就可以使用 signInWithOtp 方法让他们登录。

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

OAuth#

按照社交登录指南在 Supabase 中配置你的 OAuth 提供商。

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

对于新的和现有的用户，都使用 signInWithOAuth 方法让用户登录。这无需提前迁移现有用户，因为用户在被重定向到你的服务之前，总是需要通过 OAuth 提供者登录。

🌐 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.

在用户成功完成 OAuth 流程后，你可以通过将他们的社交提供商 ID 映射到 Auth0 来检查用户是新用户还是已有用户。Auth0 会将社交提供商 ID 存储在用户 ID 中，格式为 provider_name|provider_id（例如，github|123456）。查看更多信息请参考 Auth0 身份文档。

🌐 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.

Auth0 和 Supabase Auth 之间的映射 #

🌐 Mapping between Auth0 and Supabase Auth

每个认证提供商都有自己跟踪用户和用户信息的模式。

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

在 Supabase Auth 中，你的用户会被存储在你项目的数据库的 auth 架构下。每个用户都有一个身份（除非用户是匿名用户），它表示他们可以使用 Supabase 的登录方法。这由 auth.users 和 auth.identities 表表示。

🌐 In Supabase 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 Supabase. 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

Supabase 身份验证提供了 2 个字段，你可以用它们来映射来自 Auth0 的用户特定元数据：

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

• auth.users.raw_user_meta_data：用于存储用户可以更新的非敏感元数据（例如全名、年龄、喜欢的颜色）。
• auth.users.raw_app_meta_data：用于存储非敏感的用户元数据，用户不应能够更新这些数据（例如定价计划、访问控制角色）。

这两列都可以通过管理员用户方法访问。要创建带自定义元数据的用户，你可以使用以下方法：

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

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('your_project_url', 'your_supabase_api_key')
4
5
// ---cut---
6
const { data, error } = await supabase.auth.admin.createUser({
7
  email: 'valid.email@supabase.io',
8
  user_metadata: {
9
    full_name: 'Foo Bar',
10
  },
11
  app_metadata: {
12
    role: 'admin',
13
  },
14
})

这些字段作为列存储在 auth.users 表中，使用 jsonb 类型。可以通过管理员 updateUserById 方法 更新这两个字段。如果你想允许用户自己更新他们的 raw_user_meta_data ，可以使用 updateUser 方法。

🌐 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.

如果你有很多用户特定的元数据需要存储，建议在私有模式中创建你自己的表，并使用用户ID作为外键：

🌐 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:

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

常见问题 #

🌐 Frequently Asked Questions (FAQ)

有用的参考资料 #

🌐 Useful references

• 将12.5万用户从Auth0迁移到Supabase
• 从 Loper 到 Supabase 的迁移