auth0-ionic-react

用途

该技能用于为 Ionic React 应用（使用 Capacitor）添加 Auth0 认证能力，覆盖登录、登出以及原生深度链接回调处理，适用于 iOS 和 Android 移动端。

主要能力

• 使用 @auth0/auth0-react SDK 结合 @capacitor/browser 与 @capacitor/app 插件实现原生移动端认证。
• 通过 Capacitor Browser 插件打开 Auth0 Universal Login（WebAuth）：iOS 使用 SFSafariViewController，Android 使用 Chrome Custom Tabs。
• 认证完成后，Auth0 通过自定义 scheme 的原生回调 URL 返回应用：{packageId}://{domain}/capacitor/{packageId}/callback。
• 使用 @capacitor/app 插件捕获深度链接，并通过 handleRedirectCallback(url) 处理授权码交换。
• 支持刷新令牌（useRefreshTokens={true}、useRefreshTokensFallback={false}）以实现移动端可靠的令牌持久化。
• 提供受保护路由（withAuthenticationRequired）、获取访问令牌（getAccessTokenSilently）等能力。

使用方式

前置条件：Node.js 18+、Ionic CLI（npm install -g @ionic/cli）、已配置 Capacitor 的 Ionic React 应用、Auth0 账号与租户；iOS 需 Xcode 14+ 与 CocoaPods，Android 需 Android Studio（API level 21+）；可选安装 Auth0 CLI（brew install auth0/auth0-cli/auth0）。

快速开始工作流：

1. 配置 Auth0：可使用 Auth0 CLI 自动化设置，或在 Auth0 Dashboard 中手动配置 Native 应用并记录 Domain 与 Client ID。
2. 安装依赖：

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

1. 设置 Auth0Provider：在 src/main.tsx 中用 Auth0Provider 包裹应用根节点，配置 domain、clientId、useRefreshTokens、useRefreshTokensFallback 与 authorizationParams.redirect_uri。回调地址格式为 ${packageId}://${domain}/capacitor/${packageId}/callback。

2. 实现登录：使用 useAuth0() 的 loginWithRedirect，并在 openUrl 回调中调用 Browser.open({ url, windowName: "_self" })。

3. 处理回调：通过 CapApp.addListener('appUrlOpen', ...) 监听深度链接，当 URL 包含 state 且包含 code 或 error 时调用 handleRedirectCallback(url)，随后 Browser.close()。

4. 实现登出：调用 logout，传入 logoutParams.returnTo 与 openUrl 回调（使用 Browser.open）。

5. 构建与测试：

ionic build
npx cap sync

iOS 使用 npx cap open ios 在 Xcode 中构建；Android 使用 npx cap open android 在 Android Studio 中构建。若构建失败，可迭代 5-6 次修复；仍失败则请求用户帮助。

适用场景

• Ionic React + Capacitor 应用需要添加 Auth0 登录、登出或深度链接。
• 需要在 iOS 和 Android 上使用原生浏览器进行 Universal Login 认证。

不适用场景（应改用其他技能）：React SPA（无 Capacitor/Ionic）用 auth0-react；React Native（bare CLI）用 auth0-react-native；Expo 用 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。

限制与注意事项

• 必须在 Auth0 Dashboard 中将应用类型设为 Native。
• 回调 URL 必须严格匹配 YOUR_PACKAGE_ID://YOUR_DOMAIN/capacitor/YOUR_PACKAGE_ID/callback。
• 需启用刷新令牌：useRefreshTokens={true} 且 useRefreshTokensFallback={false}。
• 必须安装 @capacitor/browser 与 @capacitor/app，安装后需运行 npx cap sync。
• 必须处理深度链接回调，否则无法完成授权码交换。
• 不要使用 window.location.origin 作为重定向 URI，应使用自定义 URL scheme。
• 需在 Dashboard 的 Allowed Origins 中添加 capacitor://localhost 与 http://localhost。
• 移动端不应将 localStorage 视为持久存储，应使用刷新令牌。
• iOS 11+ 上 SFSafariViewController 不与 Safari 共享 Cookie，SSO 不生效属预期行为。
• 应在真机上测试认证流程，模拟器可能无法正确处理深度链接。

快速参考

• Auth0Provider：上下文提供者，用 Auth0 配置包裹应用根节点。
• useAuth0()：返回 { 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。
• CapApp.addListener('appUrlOpen', cb)：Capacitor 插件，监听深度链接事件。
• Browser.close()：Capacitor 插件，回调后关闭应用内浏览器。