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:

Pattern	Indicates
`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:

Migrating to Auth0 (replace existing auth)

Adding Auth0 alongside (keep both temporarily)

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`	认证路由

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

我在您的项目中检测到了现有身份认证功能。您是否需要：

迁移至Auth0（替换现有认证系统）

同时添加Auth0（暂时保留两者）

全新开始（移除旧认证系统，搭建新的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

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

常见迁移问题

Issue	Solution
Password hashes incompatible	Use Auth0 custom DB connection with lazy migration
Social logins don't link	Configure same social connection, users auto-link by email
Custom claims missing	Add claims via Auth0 Actions
Token format different	Update API to validate RS256 JWTs with Auth0 issuer
Session persistence	Auth0 uses rotating refresh tokens; update token storage
Users must re-login	Expected 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验证

auth0-migration

Original

Translation

Auth0 Migration Guide

Auth0迁移指南

Overview

概述

When to Use This Skill

何时使用本技能

When NOT to Use

何时不使用

Migration Approaches

迁移方法

Step 0: Detect Existing Auth Provider

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

Migration Workflow

迁移工作流

Step 1: Export Existing Users

步骤1：导出现有用户

Step 2: Import Users to Auth0

步骤2：将用户导入至Auth0

Via Auth0 CLI

Via Auth0 CLI

Step 3: Migrate Application Code

步骤3：迁移应用代码

Step 4: Update API JWT Validation

步骤4：更新API的JWT验证

Gradual Migration Strategy

渐进式迁移策略

Phase 1: Parallel Auth

阶段1：并行认证

Phase 2: New Users on Auth0

阶段2：新用户使用Auth0

Phase 3: Forced Migration

阶段3：强制迁移

Phase 4: Cleanup

阶段4：清理

Common Migration Issues

常见迁移问题

Reference Documentation

参考文档

User Import

用户导入

Code Migration

代码迁移

Related Skills

相关技能

Core Integration

核心集成

SDK Skills

SDK技能

References

参考链接