auth0-react-native

Auth0 React Native 集成

使用 react-native-auth0 为 React Native 和 Expo 移动应用添加身份验证。

---

前置条件

• React Native 或 Expo 应用
• 已配置为 Native 类型的 Auth0 账户和应用
• 如果尚未设置 Auth0，请先使用 auth0-quickstart skill

不适用场景

• Expo 托管工作流 - 对带有配置插件的 Expo 应用，请使用 auth0-expo skill
• React Web 应用 - 对 SPA（Vite/CRA），请使用 auth0-react skill
• React Server Components - 对 Next.js 应用，请使用 auth0-nextjs
• 非 React Native 应用 - 请使用平台专用 SDK（iOS 使用 Swift，Android 使用 Kotlin）
• 后端 API - 请使用适用于服务器语言的 JWT 验证库

---

快速入门工作流

1. 安装 SDK

Expo：

npx expo install react-native-auth0

React Native CLI：

npm install react-native-auth0
npx pod-install  # iOS only

2. 配置环境

如需使用 Auth0 CLI 自动设置，请参阅设置指南，查看完整脚本。

如需手动设置：

创建 .env：

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id

3. 配置原生平台

iOS - 更新 ios/{YourApp}/Info.plist：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>None</string>
    <key>CFBundleURLName</key>
    <string>auth0</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>$(PRODUCT_BUNDLE_IDENTIFIER).auth0</string>
    </array>
  </dict>
</array>

Android - 更新 android/app/src/main/AndroidManifest.xml：

<activity
    android:name="com.auth0.android.provider.RedirectActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="YOUR_AUTH0_DOMAIN"
            android:pathPrefix="/android/${applicationId}/callback"
            android:scheme="${applicationId}" />
    </intent-filter>
</activity>

Expo - 更新 app.json：

{
  "expo": {
    "scheme": "your-app-scheme",
    "ios": {
      "bundleIdentifier": "com.yourcompany.yourapp"
    },
    "android": {
      "package": "com.yourcompany.yourapp"
    }
  }
}

4. 使用 Auth0Provider 添加身份验证

使用 Auth0Provider 包裹应用：

import React from 'react';
import { Auth0Provider } from 'react-native-auth0';
import App from './App';

export default function Root() {
  return (
    <Auth0Provider
      domain={process.env.AUTH0_DOMAIN}
      clientId={process.env.AUTH0_CLIENT_ID}
    >
      <App />
    </Auth0Provider>
  );
}

5. 使用 useAuth0 Hook

import React from 'react';
import { View, Button, Text, ActivityIndicator } from 'react-native';
import { useAuth0 } from 'react-native-auth0';

export default function App() {
  const { user, authorize, clearSession, isLoading } = useAuth0();

  const login = async () => {
    try {
      await authorize({
        scope: 'openid profile email'
      });
    } catch (error) {
      console.error('Login error:', error);
    }
  };

  const logout = async () => {
    try {
      await clearSession();
    } catch (error) {
      console.error('Logout error:', error);
    }
  };

  if (isLoading) {
    return <ActivityIndicator />;
  }

  return (
    <View>
      {user ? (
        <>
          <Text>Welcome, {user.name}!</Text>
          <Text>{user.email}</Text>
          <Button title="Logout" onPress={logout} />
        </>
      ) : (
        <Button title="Login" onPress={login} />
      )}
    </View>
  );
}

6. 测试身份验证

Expo：

npx expo start

React Native：

npx react-native run-ios
# or
npx react-native run-android

---

详细文档

• 设置指南 - 自动设置、原生配置、深层链接
• 模式指南 - 安全存储、生物识别身份验证、令牌刷新
• API 参考 - 完整的 SDK API、方法和配置选项

---

常见错误

错误	修复方法
忘记使用 Auth0Provider 包裹应用	所有使用 useAuth0() 的组件都必须是 Auth0Provider 的子组件
忘记配置深层链接	将 URL 方案添加到 iOS Info.plist 和 Android AndroidManifest.xml（参见步骤 3）
回调 URL 不匹配	确保 Auth0 Dashboard 中的回调 URL 与应用的 URL 方案匹配（例如，com.yourapp.auth0://YOUR_DOMAIN/ios/com.yourapp/callback）
安装后 iOS 构建失败	运行 npx pod-install 以链接原生依赖项
在 Auth0 中将应用创建为 SPA 类型	移动应用必须使用 Native 应用类型
未处理身份验证错误	将 authorize/clearSession 调用包装在 try-catch 代码块中
Android 上深层链接无法使用	确认 RedirectActivity 上已设置 android:exported="true"

---

相关技能

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

---

快速参考

核心 Hook API：

• useAuth0() - 身份验证主 Hook
• authorize() - 发起登录
• clearSession() - 登出
• user - 用户个人资料对象
• getCredentials() - 获取用于 API 调用的令牌
• isLoading - 加载状态

常见用例：

• 登录/登出 → 参见上文步骤 5
• 安全令牌存储 → 由 Auth0Provider 自动完成
• 生物识别身份验证 → 模式指南
• 使用令牌调用 API → 模式指南
• 令牌刷新 → 由 getCredentials() 自动完成

---

参考资料

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