auth0-ionic-react

Auth0 Ionic React（Capacitor）集成

使用 Capacitor 为 Ionic React 应用添加 Auth0 身份验证。本技能介绍如何将 @auth0/auth0-react SDK 与 @capacitor/browser 和 @capacitor/app 插件结合，在 iOS 和 Android 上实现原生移动身份验证和深度链接处理。

前提条件

• Node.js 18+
• Ionic CLI（npm install -g @ionic/cli）
• 已配置 Capacitor 的 Ionic React 应用
• Auth0 账户和租户
• iOS：Xcode 14+ 和 CocoaPods
• Android：Android Studio 和 API 级别 21+
• Auth0 CLI — brew install auth0/auth0-cli/auth0

不适用的场景

使用场景	推荐技能
React SPA（无 Capacitor/Ionic）	auth0-react
React Native（裸 CLI）	auth0-react-native
Expo（React Native）	auth0-expo
Ionic + Angular + Capacitor	auth0-ionic-angular
Ionic + Vue + Capacitor	auth0-ionic-vue
Next.js（服务端）	auth0-nextjs
iOS 原生（Swift）	auth0-swift
Android 原生（Kotlin）	auth0-android

快速入门工作流

步骤 1：配置 Auth0

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

手动设置时，请在 Auth0 Dashboard 中配置一个 Native 应用，并记下 Domain 和 Client ID。

步骤 2：安装依赖项

npm install @auth0/auth0-react @capacitor/browser @capacitor/app
npx cap sync

步骤 3：设置 Auth0Provider

使用针对 Capacitor 配置的 Auth0Provider 包装应用根组件。在 src/main.tsx 中：

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

const domain = import.meta.env.VITE_AUTH0_DOMAIN;
const clientId = import.meta.env.VITE_AUTH0_CLIENT_ID;
const packageId = import.meta.env.VITE_AUTH0_PACKAGE_ID; // e.g., com.example.myapp

const redirectUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;

createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      useRefreshTokens={true}
      useRefreshTokensFallback={false}
      authorizationParams={{
        redirect_uri: redirectUri
      }}
    >
      <App />
    </Auth0Provider>
  </React.StrictMode>
);

步骤 4：使用 Capacitor Browser 实现登录

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

const { loginWithRedirect } = useAuth0();

const login = async () => {
  await loginWithRedirect({
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

步骤 5：通过深度链接处理回调

import { useEffect } from 'react';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { useAuth0 } from '@auth0/auth0-react';

const { handleRedirectCallback } = useAuth0();

useEffect(() => {
  const listener = CapApp.addListener('appUrlOpen', async ({ url }) => {
    if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
      await handleRedirectCallback(url);
    }
    await Browser.close();
  });

  return () => {
    listener.then(l => l.remove());
  };
}, [handleRedirectCallback]);

步骤 6：实现登出

const doLogout = async () => {
  await logout({
    logoutParams: {
      returnTo: `${packageId}://${domain}/capacitor/${packageId}/callback`
    },
    async openUrl(url) {
      await Browser.open({ url, windowName: "_self" });
    }
  });
};

步骤 7：构建和测试

Agent 指令： 集成后，请验证构建：

ionic build
npx cap sync

对于 iOS：运行 npx cap open ios，然后在 Xcode 中构建。 对于 Android：运行 npx cap open android，然后在 Android Studio 中构建。 如果构建失败，请尝试修复问题，最多迭代 5-6 次。如果仍然失败，请使用 AskUserQuestion 请求帮助。

详细文档

• 设置指南 — Auth0 CLI 配置、Capacitor URL 方案注册、密钥管理
• 集成模式 — 使用 Capacitor Browser 登录/登出、深度链接回调处理、用户资料、受保护路由、令牌访问、错误处理
• 测试与参考 — Auth0Provider 属性、useAuth0 钩子、Capacitor 插件配置的完整 API 参考、测试清单、常见问题

常见错误

错误	修复方法
Auth0 Dashboard 中的应用类型未设为 Native	在 Dashboard 设置中将应用类型改为“Native”
回调 URL 格式缺失或不正确	使用 YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback — 必须完全匹配
未启用刷新令牌	在 Auth0Provider 上设置 useRefreshTokens={true} 和 useRefreshTokensFallback={false}
缺少 @capacitor/browser 或 @capacitor/app	安装两者：npm install @capacitor/browser @capacitor/app && npx cap sync
未处理深度链接回调	添加 CapApp.addListener('appUrlOpen', ...) 以处理 Auth0 重定向
安装后忘记运行 npx cap sync	安装 Capacitor 插件后务必运行 npx cap sync
将 window.location.origin 用作重定向 URI	使用自定义 URL 方案（packageId://domain/...），而不是 http://localhost
Dashboard 中缺少 Allowed Origins	将 capacitor://localhost, http://localhost 添加到 Allowed Origins
将 localStorage 视为移动设备上的持久存储	使用刷新令牌（useRefreshTokens={true}），以可靠地持久保存令牌
iOS SSO 无法使用	SFSafariViewController 在 iOS 11+ 上不会与 Safari 共享 Cookie；这是预期行为
未在实体设备上测试	务必在实体设备上测试身份验证流程；模拟器可能无法正确处理深度链接

WebAuth 方法

此 SDK 通过 Capacitor Browser 插件使用 Auth0 的 Universal Login（WebAuth）。loginWithRedirect() 方法会在系统浏览器中打开 Auth0 授权端点（iOS 上为 SFSafariViewController，Android 上为 Chrome Custom Tabs）。身份验证完成后，Auth0 会通过自定义 scheme 的原生回调 URL 将用户重定向回应用：{packageId}://{domain}/capacitor/{packageId}/callback。@capacitor/app 插件会捕获此深层链接，handleRedirectCallback(url) 则会处理授权码交换。

不同于使用 https://{domain}/android/{packageId}/callback 或 https://{domain}/ios/{bundleId}/callback 的标准原生 SDK，Ionic Capacitor 应用使用 Capacitor 专用回调路径，并将 package ID 作为 URL scheme。

相关技能

• auth0-react — React SPA（仅限浏览器，不使用 Capacitor）
• auth0-ionic-angular — 使用 Angular 和 Capacitor 的 Ionic
• auth0-ionic-vue — 使用 Vue 和 Capacitor 的 Ionic
• auth0-react-native — React Native（裸 CLI，不使用 Ionic/Capacitor）
• auth0-expo — 使用 Auth0 的 Expo（React Native）

快速参考

API	描述
Auth0Provider	Context provider — 使用 Auth0 配置包裹应用根节点
useAuth0()	Hook — 返回 { isLoading, isAuthenticated, user, loginWithRedirect, logout, getAccessTokenSilently, handleRedirectCallback }
loginWithRedirect({ openUrl })	通过 Universal Login 登录 — 在 openUrl 回调中使用 Browser.open()
logout({ logoutParams, openUrl })	登出 — 在 openUrl 回调中使用 Browser.open()
handleRedirectCallback(url)	处理来自深层链接的 Auth0 回调 URL
getAccessTokenSilently()	获取访问令牌（在移动设备上使用刷新令牌）
withAuthenticationRequired(Component)	用于保护路由的 HOC
Browser.open({ url })	Capacitor — 在系统浏览器中打开 URL（SFSafariViewController / Chrome Custom Tabs）
CapApp.addListener('appUrlOpen', cb)	Capacitor — 监听深层链接事件
Browser.close()	Capacitor — 在回调后关闭应用内浏览器

参考资料

• Auth0 Ionic React 快速入门
• Auth0 React SDK GitHub
• Auth0 React SDK API 参考
• Ionic React Capacitor 示例应用
• Capacitor Browser 插件
• Capacitor App 插件
• Auth0 控制台