auth0-migration

Auth0 迁移指南

将用户和身份验证流程从现有身份验证提供商迁移到 Auth0。

---

概述

何时使用此技能

• 从其他身份验证提供商迁移到 Auth0
• 批量导入现有用户
• 逐步迁移活跃用户群
• 更新 API 中的 JWT 验证

何时不使用

• 从头开始使用 Auth0——对于没有现有用户的新项目，请使用 auth0-quickstart
• 已经在使用 Auth0——此指南用于迁移到 Auth0，而不是在 Auth0 租户之间迁移
• 仅添加 MFA 或功能——如果只是添加功能，请使用对应的功能专用技能

迁移方式

• **批量迁移：**一次性导入用户（推荐用于规模较小或不活跃的用户群）
• **渐进式迁移：**随时间逐步进行惰性迁移（推荐用于规模较大且活跃的用户群）
• **混合迁移：**导入不活跃用户，对活跃用户进行惰性迁移

---

步骤 0：检测现有身份验证提供商

检查项目是否已配置身份验证：

在代码库中搜索常见的身份验证相关模式：

模式	表示
signInWithEmailAndPassword, onAuthStateChanged	Firebase Auth
useUser, useSession, isSignedIn	现有身份验证钩子
passport.authenticate, LocalStrategy	Passport.js
authorize, getAccessToken, oauth	OAuth/OIDC
JWT, jwt.verify, jsonwebtoken	基于令牌的身份验证
/api/auth/, /login, /callback	身份验证路由

如果检测到现有身份验证，请询问：

我检测到你的项目中已有身份验证。你要：

1. 迁移到 Auth0（替换现有身份验证）
2. 在现有身份验证之外添加 Auth0（暂时同时保留两者）
3. 从头开始（移除旧身份验证，配置全新的 Auth0）

---

迁移工作流

步骤 1：导出现有用户

从当前提供商导出用户。详细说明请参阅用户导入指南：

• 从 Firebase 导出
• 从 AWS Cognito 导出
• 从 Supabase 导出
• 从自定义数据库导出

每位用户的必需数据：

• 电子邮件地址
• 电子邮件验证状态
• 密码哈希（如果可用）
• 用户元数据/个人资料数据
• 创建时间戳

---

步骤 2：将用户导入 Auth0

通过 Dashboard、CLI 或 Management API 导入用户。

快速入门：

# Via Auth0 CLI
auth0 api post "jobs/users-imports" \
  --data "connection_id=con_ABC123" \
  --data "[email protected]"

详细说明：

• 用户 JSON 格式
• 密码哈希算法
• 导入方法
• 监控导入进度
• 常见导入错误

---

步骤 3：迁移应用代码

更新应用代码以使用 Auth0 SDK。

请参阅代码迁移模式，了解详细的迁移前后示例：

前端：

• React 迁移
• Next.js 迁移
• Vue.js 迁移
• Angular 迁移
• React Native 迁移

后端：

• Express.js 迁移
• API JWT 验证

特定提供商迁移：

• 从 Firebase 迁移到 Auth0
• 从 Supabase 迁移到 Auth0
• 从 Clerk 迁移到 Auth0

代码迁移完成后，请使用对应框架的技能：

• React 应用使用 auth0-react
• Next.js 应用使用 auth0-nextjs
• Vue.js 应用使用 auth0-vue
• Angular 应用使用 auth0-angular
• Express.js 应用使用 auth0-express
• React Native/Expo 应用使用 auth0-react-native

---

步骤 4：更新 API JWT 验证

如果 API 会验证 JWT，请更新验证逻辑，以验证 Auth0 令牌。

主要区别：

• 算法： HS256（对称）→ RS256（非对称）
• 颁发者： 自定义 → https://YOUR_TENANT.auth0.com/
• JWKS URL： https://YOUR_TENANT.auth0.com/.well-known/jwks.json

请参阅 JWT 验证示例，了解：

• Node.js / Express 实现
• Python / Flask 实现
• 主要区别和迁移检查清单

---

渐进式迁移策略

对于有活跃用户的生产应用，请采用分阶段方案：

阶段 1：并行认证

同时支持 Auth0 和旧提供商：

// Support both providers during migration
const getUser = async () => {
  // Try Auth0 first
  const auth0User = await getAuth0User();
  if (auth0User) return auth0User;

  // Fall back to legacy provider
  return await getLegacyUser();
};

阶段 2：新用户使用 Auth0

• 所有新注册用户都使用 Auth0
• 现有用户继续使用旧提供商
• 在用户下次登录时迁移（延迟迁移）

阶段 3：强制迁移

• 提示剩余用户“更新账户”
• 通过 Auth0 发送密码重置邮件
• 设置关闭旧系统的截止日期

阶段 4：清理

• 移除旧版认证代码
• 归档用户导出文件以满足合规要求
• 更新文档

---

常见迁移问题

问题	解决方案
密码哈希不兼容	使用 Auth0 自定义数据库连接进行延迟迁移
社交登录未关联	配置相同的社交连接，系统会按电子邮件自动关联用户
缺少自定义声明	通过 Auth0 Actions 添加声明
令牌格式不同	更新 API，使其使用 Auth0 颁发者验证 RS256 JWT
会话持久化	Auth0 使用轮换刷新令牌；请更新令牌存储方式
用户必须重新登录	基于重定向的认证中这是预期行为；请告知用户

---

参考文档

用户导入

导出和导入用户的完整指南：

• 从常见提供商导出
• 用户 JSON 格式
• 密码哈希算法
• 导入方法
• 监控与故障排查

代码迁移

所有主要框架的迁移前后示例：

• React 模式
• Next.js 模式
• Express 模式
• Vue.js 模式
• Angular 模式
• React Native 模式
• API JWT 验证

---

相关技能

核心集成

• auth0-quickstart - 迁移后初始设置 Auth0

SDK 技能

• auth0-react - React SPA 集成
• auth0-nextjs - Next.js 集成
• auth0-vue - Vue.js 集成
• auth0-angular - Angular 集成
• auth0-express - Express.js 集成
• auth0-react-native - React Native/Expo 集成

---

参考资料

• Auth0 用户迁移文档
• 批量导入用户
• 密码哈希算法
• Management API - 用户导入