auth0-react

Auth0 React 集成

使用 @auth0/auth0-react 为 React 单页应用添加身份验证。

---

前置条件

• React 16.11+ 应用（Vite 或 Create React App）——支持 React 16、17、18 和 19
• 已配置 Auth0 账户和应用程序
• 如果尚未设置 Auth0，请先使用 auth0-quickstart skill

不适用场景

• Next.js 应用——App Router 和 Pages Router 均请使用 auth0-nextjs skill
• React Native 移动应用——iOS/Android 请使用 auth0-react-native skill
• 服务端渲染的 React——使用特定框架的 SDK（Next.js、Remix 等）
• 嵌入式登录——此 SDK 使用 Auth0 Universal Login（基于重定向）
• 后端 API 身份验证——改用 express-openid-connect 或 JWT 验证

---

快速入门工作流

1. 安装 SDK

npm install @auth0/auth0-react

2. 配置环境

使用 Auth0 CLI 自动设置时，请参阅设置指南获取完整脚本。

手动设置时：

创建 .env 文件：

Vite：

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

Create React App：

REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-client-id

3. 使用 Auth0Provider 包装应用

更新 src/main.tsx（Vite）或 src/index.tsx（CRA）：

import React from 'react';
import ReactDOM from 'react-dom/client';
import { Auth0Provider } from '@auth0/auth0-react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={import.meta.env.VITE_AUTH0_DOMAIN} // or process.env.REACT_APP_AUTH0_DOMAIN
      clientId={import.meta.env.VITE_AUTH0_CLIENT_ID}
      authorizationParams={{
        redirect_uri: window.location.origin
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

4. 添加身份验证界面

import { useAuth0 } from '@auth0/auth0-react';

export function LoginButton() {
  const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();

  if (isLoading) return <div>Loading...</div>;

  if (isAuthenticated) {
    return (
      <div>
        <span>Welcome, {user?.name}</span>
        <button onClick={() => logout({ logoutParams: { returnTo: window.location.origin } })}>
          Logout
        </button>
      </div>
    );
  }

  return <button onClick={() => loginWithRedirect()}>Login</button>;
}

5. 测试身份验证

启动开发服务器并测试登录流程：

npm run dev  # Vite
# or
npm start    # CRA

---

详细文档

• 设置指南——自动设置脚本（Bash/PowerShell）、CLI 命令、手动配置
• 集成指南——受保护的路由、API 调用、错误处理、高级模式
• API 参考——完整 SDK API、配置选项、钩子参考、测试策略

---

常见错误

错误	修复方法
忘记在 Auth0 Dashboard 中添加重定向 URI	将应用程序 URL（例如 http://localhost:3000、https://app.example.com）添加到 Auth0 Dashboard 的 Allowed Callback URLs 中
使用了错误的环境变量前缀	Vite 使用 VITE_ 前缀，Create React App 使用 REACT_APP_
未处理加载状态	渲染依赖身份验证的界面前，始终检查 isLoading
将令牌存储在 localStorage 中	切勿手动存储令牌——SDK 会自动安全地处理存储
缺少 Auth0Provider 包装器	整个应用必须使用 <Auth0Provider> 包装
Provider 不在根级别	Auth0Provider 必须包装所有使用身份验证钩子的组件
环境变量导入路径错误	Vite 使用 import.meta.env.VITE_*，CRA 使用 process.env.REACT_APP_*
使用 acr_values 重定向进行应用内 MFA	使用 useAuth0().mfa API 进行应用内注册/质询/验证流程
未捕获 MfaRequiredError	将 getAccessTokenSilently 放入 try/catch 中，并检查 instanceof MfaRequiredError
直接调用 MFA 端点	使用 useAuth0() 中的 mfa 属性——它会自动处理令牌管理
忘记为 step-up MFA 启用刷新令牌	使用 interactiveErrorHandler="popup" 时，在 Auth0Provider 上设置 useRefreshTokens={true}

---

相关技能

• auth0-quickstart - Auth0 基础设置
• auth0-migration - 从其他身份验证提供商迁移
• auth0-mfa - 添加多因素身份验证
• auth0-cli - 从终端管理 Auth0 资源

---

快速参考

核心 Hooks：

• useAuth0() - 主要的身份验证 Hook
• isAuthenticated - 检查用户是否已登录
• user - 用户个人资料信息
• loginWithRedirect() - 发起登录
• logout() - 退出用户账号
• getAccessTokenSilently() - 获取用于 API 调用的访问令牌
• mfa - 用于注册、质询和验证的 MFA API 客户端
  • mfa.getAuthenticators(mfaToken) - 列出已注册的验证器
  • mfa.getEnrollmentFactors(mfaToken) - 获取可用的注册方式
  • mfa.enroll(params) - 注册新的验证器（OTP、SMS、Email、Voice、Push）
  • mfa.challenge(params) - 发起 MFA 质询
  • mfa.verify(params) - 验证 MFA 质询并完成身份验证

MFA 错误类型（从 @auth0/auth0-react 导入）：

• MfaRequiredError - 当需要 MFA 时由 getAccessTokenSilently 抛出（包含 mfa_token 和 mfa_requirements）
• MfaEnrollmentError、MfaChallengeError、MfaVerifyError - 由相应的 mfa.* 方法抛出

常见用例：

• 登录/退出按钮 → 请参见上方的步骤 4
• 受保护的路由 → 集成指南
• 使用令牌调用 API → 集成指南
• 错误处理 → 集成指南
• MFA 处理 → 集成指南

---

参考资料

• Auth0 React SDK 文档
• Auth0 React 快速入门
• SDK GitHub 仓库