Back to Details

auth0-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Auth0 Migration Guide

Auth0迁移指南

Migrate users and authentication flows from existing auth providers to Auth0.
将用户和身份认证流程从现有身份认证提供商迁移至Auth0。

Overview

概述

When to Use This Skill

何时使用本技能

  • Migrating from another auth provider to Auth0
  • Bulk importing existing users
  • Gradually transitioning active user bases
  • Updating JWT validation in APIs
  • 从其他身份认证提供商迁移至Auth0
  • 批量导入现有用户
  • 逐步过渡活跃用户群
  • 更新API中的JWT验证

When NOT to Use

何时不使用

  • Starting fresh with Auth0 - Use 
    auth0-quickstart
    for new projects without existing users
  • Already using Auth0 - This is for migrating TO Auth0, not between Auth0 tenants
  • Only adding MFA or features - Use feature-specific skills if just adding capabilities
  • 全新开始使用Auth0 - 对于没有现有用户的新项目，请使用
    auth0-quickstart
  • 已在使用Auth0 - 本指南适用于迁移至Auth0，而非在Auth0租户之间迁移
  • 仅添加MFA或其他功能 - 如果只是添加功能，请使用特定功能的技能

Migration Approaches

迁移方法

  • Bulk Migration: One-time user import (recommended for small/inactive bases)
  • Gradual Migration: Lazy migration over time (recommended for large active bases)
  • Hybrid: Import inactive users, lazy-migrate active users
  • 批量迁移： 一次性导入用户（推荐用于小型/不活跃用户群）
  • 渐进式迁移： 随时间推移进行惰性迁移（推荐用于大型活跃用户群）
  • 混合迁移： 导入不活跃用户，对活跃用户进行惰性迁移

Step 0: Detect Existing Auth Provider

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

Check if the project already has authentication:
Search for common auth-related patterns in the codebase:
PatternIndicates
signInWithEmailAndPassword
, 
onAuthStateChanged
Firebase Auth
useUser
, 
useSession
, 
isSignedIn
Existing auth hooks
passport.authenticate
, 
LocalStrategy
Passport.js
authorize
, 
getAccessToken
, 
oauth
OAuth/OIDC
JWT
, 
jwt.verify
, 
jsonwebtoken
Token-based auth
/api/auth/
, 
/login
, 
/callback
Auth routes
If existing auth detected, ask:
I detected existing authentication in your project. Are you:
  1. Migrating to Auth0 (replace existing auth)
  2. Adding Auth0 alongside (keep both temporarily)
  3. Starting fresh (remove old auth, new Auth0 setup)
检查项目是否已存在身份认证功能：
在代码库中搜索常见的身份认证相关模式：
模式对应提供商
signInWithEmailAndPassword
, 
onAuthStateChanged
Firebase Auth
useUser
, 
useSession
, 
isSignedIn
现有自定义认证钩子
passport.authenticate
, 
LocalStrategy
Passport.js
authorize
, 
getAccessToken
, 
oauth
OAuth/OIDC
JWT
, 
jwt.verify
, 
jsonwebtoken
基于Token的认证
/api/auth/
, 
/login
, 
/callback
认证路由
如果检测到现有身份认证，询问：
我在您的项目中检测到了现有身份认证功能。您是否需要：
  1. 迁移至Auth0（替换现有认证系统）
  2. 同时添加Auth0（暂时保留两者）
  3. 全新开始（移除旧认证系统，搭建新的Auth0环境）

Migration Workflow

迁移工作流

Step 1: Export Existing Users

步骤1：导出现有用户

Export users from your current provider. See User Import Guide for detailed instructions:
  • Exporting from Firebase
  • Exporting from AWS Cognito
  • Exporting from Supabase
  • Exporting from Custom Database
Required data per user:
  • Email address
  • Email verified status
  • Password hash (if available)
  • User metadata/profile data
  • Creation timestamp
从当前提供商导出用户。详细说明请参见用户导入指南：
  • 从Firebase导出
  • 从AWS Cognito导出
  • 从Supabase导出
  • 从自定义数据库导出
每个用户所需数据：
  • 电子邮箱地址
  • 邮箱验证状态
  • 密码哈希（如果可用）
  • 用户元数据/个人资料数据
  • 创建时间戳

Step 2: Import Users to Auth0

步骤2：将用户导入至Auth0

Import users via Dashboard, CLI, or Management API.
Quick start:
bash
undefined
通过控制台、CLI或管理API导入用户。
快速开始：
bash
undefined

Via Auth0 CLI

Via Auth0 CLI

auth0 api post "jobs/users-imports"
--data "connection_id=con_ABC123"
--data "users=@users.json"

**For detailed instructions:**
- [User JSON Format](references/user-import.md#auth0-user-import-format)
- [Password Hash Algorithms](references/user-import.md#password-hash-algorithms)
- [Import Methods](references/user-import.md#importing-to-auth0)
- [Monitoring Import Progress](references/user-import.md#monitoring-import-progress)
- [Common Import Errors](references/user-import.md#common-import-errors)

---
auth0 api post "jobs/users-imports"
--data "connection_id=con_ABC123"
--data "users=@users.json"

**详细说明请参见：**
- [用户JSON格式](references/user-import.md#auth0-user-import-format)
- [密码哈希算法](references/user-import.md#password-hash-algorithms)
- [导入方法](references/user-import.md#importing-to-auth0)
- [监控导入进度](references/user-import.md#monitoring-import-progress)
- [常见导入错误](references/user-import.md#common-import-errors)

---

Step 3: Migrate Application Code

步骤3：迁移应用代码

Update your application code to use Auth0 SDKs.
See Code Migration Patterns for detailed before/after examples:
Frontend:
  • React Migration
  • Next.js Migration
  • Vue.js Migration
  • Angular Migration
  • React Native Migration
Backend:
  • Express.js Migration
  • API JWT Validation
Provider-Specific:
  • Firebase to Auth0
  • Supabase to Auth0
  • Clerk to Auth0
After migrating code, use framework-specific skills:
  • auth0-react
    for React applications
  • auth0-nextjs
    for Next.js applications
  • auth0-vue
    for Vue.js applications
  • auth0-angular
    for Angular applications
  • auth0-express
    for Express.js applications
  • auth0-react-native
    for React Native/Expo applications
更新您的应用代码以使用Auth0 SDK。
详细的前后示例请参见代码迁移模式：
前端：
  • React迁移
  • Next.js迁移
  • Vue.js迁移
  • Angular迁移
  • React Native迁移
后端：
  • Express.js迁移
  • API JWT验证
特定提供商迁移：
  • Firebase至Auth0
  • Supabase至Auth0
  • Clerk至Auth0
代码迁移完成后，请使用框架专属技能：
  • auth0-react
    用于React应用
  • auth0-nextjs
    用于Next.js应用
  • auth0-vue
    用于Vue.js应用
  • auth0-angular
    用于Angular应用
  • auth0-express
    用于Express.js应用
  • auth0-react-native
    用于React Native/Expo应用

Step 4: Update API JWT Validation

步骤4：更新API的JWT验证

If your API validates JWTs, update to validate Auth0 tokens.
Key differences:
  • Algorithm: HS256 (symmetric) → RS256 (asymmetric)
  • Issuer: Custom → 
    https://YOUR_TENANT.auth0.com/
  • JWKS URL: 
    https://YOUR_TENANT.auth0.com/.well-known/jwks.json
See JWT Validation Examples for:
  • Node.js / Express implementation
  • Python / Flask implementation
  • Key differences and migration checklist
如果您的API需要验证JWT，请更新为验证Auth0令牌。
主要差异：
  • 算法： HS256（对称）→ RS256（非对称）
  • 签发者： 自定义 → 
    https://YOUR_TENANT.auth0.com/
  • JWKS地址： 
    https://YOUR_TENANT.auth0.com/.well-known/jwks.json
详细实现示例请参见JWT验证示例：
  • Node.js / Express实现
  • Python / Flask实现
  • 主要差异及迁移检查清单

Gradual Migration Strategy

渐进式迁移策略

For production applications with active users, use a phased approach:
对于拥有活跃用户的生产应用，请采用分阶段方法：

Phase 1: Parallel Auth

阶段1：并行认证

Support both Auth0 and legacy provider simultaneously:
typescript
// 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();
};
同时支持Auth0和旧版提供商：
typescript
// 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();
};

Phase 2: New Users on Auth0

阶段2：新用户使用Auth0

  • All new signups go to Auth0
  • Existing users continue on legacy provider
  • Migrate users on next login (lazy migration)
  • 所有新注册用户使用Auth0
  • 现有用户继续使用旧版提供商
  • 用户下次登录时进行迁移（惰性迁移）

Phase 3: Forced Migration

阶段3：强制迁移

  • Prompt remaining users to "update account"
  • Send password reset emails via Auth0
  • Set deadline for legacy system shutdown
  • 提示剩余用户“更新账户”
  • 通过Auth0发送密码重置邮件
  • 设置旧版系统关闭截止日期

Phase 4: Cleanup

阶段4：清理

  • Remove legacy auth code
  • Archive user export for compliance
  • Update documentation
  • 移除旧版认证代码
  • 归档用户导出数据以符合合规要求
  • 更新文档

Common Migration Issues

常见迁移问题

IssueSolution
Password hashes incompatibleUse Auth0 custom DB connection with lazy migration
Social logins don't linkConfigure same social connection, users auto-link by email
Custom claims missingAdd claims via Auth0 Actions
Token format differentUpdate API to validate RS256 JWTs with Auth0 issuer
Session persistenceAuth0 uses rotating refresh tokens; update token storage
Users must re-loginExpected for redirect-based auth; communicate to users
问题解决方案
密码哈希不兼容使用Auth0自定义数据库连接并结合惰性迁移
社交登录无法关联配置相同的社交连接，用户将通过邮箱自动关联
缺少自定义声明通过Auth0 Actions添加声明
令牌格式不同更新API以验证带有Auth0签发者的RS256 JWT
会话持久化Auth0使用轮换刷新令牌；更新令牌存储方式
用户必须重新登录基于重定向的认证会出现此情况；提前告知用户

Reference Documentation

参考文档

User Import

用户导入

Complete guide to exporting and importing users:
  • Exporting from Common Providers
  • User JSON Format
  • Password Hash Algorithms
  • Import Methods
  • Monitoring & Troubleshooting
导出和导入用户的完整指南：
  • 从常见提供商导出
  • 用户JSON格式
  • 密码哈希算法
  • 导入方法
  • 监控与故障排除

Code Migration

代码迁移

Before/after examples for all major frameworks:
  • React Patterns
  • Next.js Patterns
  • Express Patterns
  • Vue.js Patterns
  • Angular Patterns
  • React Native Patterns
  • API JWT Validation
所有主流框架的前后示例：
  • React模式
  • Next.js模式
  • Express模式
  • Vue.js模式
  • Angular模式
  • React Native模式
  • API JWT验证

Related Skills

相关技能

Core Integration

核心集成

  • auth0-quickstart
    - Initial Auth0 setup after migration
  • auth0-quickstart
    - 迁移完成后的初始Auth0设置

SDK Skills

SDK技能

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

References

参考链接