auth0-ionic-angular

用途

本技能用于为使用 Capacitor 的 Ionic Angular 应用添加认证能力，基于 @auth0/auth0-angular SDK 与 Capacitor 插件实现原生 iOS 与 Android 上的认证。它覆盖登录、登出、用户资料展示，以及通过系统浏览器进行的令牌管理。

主要能力

使用 Auth0 进行登录与登出
展示用户资料（姓名、邮箱、头像）
通过系统浏览器完成认证：iOS 使用 SFSafariViewController，Android 使用 Chrome Custom Tabs
借助 Capacitor Browser 插件与 @capacitor/app 处理深度链接回调
安全令牌管理（在移动端使用刷新令牌）

前置条件

Node.js 20+ 与 npm 10+
Ionic CLI（npm install -g @ionic/cli）
项目中已配置 Capacitor 5+
Auth0 CLI（用于自动配置）：brew install auth0/auth0-cli/auth0
一个 Auth0 账号（免费套餐可用）

安装与配置流程

安装依赖： npm install @auth0/auth0-angular @capacitor/browser @capacitor/app
配置 Auth0：技能要求先让开发者选择“自动配置（推荐）”或“手动配置”，即使提示中已提供凭据。Auth0 Dashboard 的 Native 应用需设置：
- Application Type：Native
- Allowed Callback URLs：PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback
- Allowed Logout URLs：PACKAGE_ID://YOUR_DOMAIN/capacitor/PACKAGE_ID/callback
- Allowed Origins：capacitor://localhost, http://localhost 其中 PACKAGE_ID 为 capacitor.config.ts 中的 appId，YOUR_DOMAIN 为 Auth0 域。本地 Web 开发（ionic serve）时还需加入 http://localhost:8100。
配置 SDK：在 app.module.ts（NgModule）或 app.config.ts（standalone）中使用 provideAuth0() 或 AuthModule.forRoot()，设置 domain、clientId、useRefreshTokens: true、useRefreshTokensFallback: false，并在 authorizationParams 中指定 redirect_uri。
处理深度链接回调：在 AppComponent 根组件注册 CapApp.addListener('appUrlOpen', ...)，在 ngZone.run() 中调用 auth.handleRedirectCallback(url) 并 Browser.close()。
实现登录：调用 auth.loginWithRedirect()，通过自定义 openUrl 使用 Browser.open({ url, windowName: '_self' })。
实现登出：调用 auth.logout()，设置 logoutParams.returnTo，并使用自定义 openUrl。
展示用户资料：使用 auth.user$ 异步管道渲染用户信息。
构建与测试： npm run build npx cap sync

WebAuth 认证流程

用户点击登录 → 应用调用 loginWithRedirect，并通过 Browser.open() 打开 URL
Capacitor Browser 插件在系统浏览器中打开 Auth0 Universal Login 页面
用户认证 → Auth0 重定向到自定义 URL scheme 回调
操作系统将深度链接路由到应用 → 触发 appUrlOpen 事件
handleRedirectCallback(url) 在 ngZone.run() 内处理授权码交换
Browser.close() 关闭系统浏览器
auth.isAuthenticated$ 发出 true，auth.user$ 发出用户资料

常见错误

Auth0 应用类型误设为 SPA 而非 Native：在 Dashboard 改为 Native
缺少回调 URL：需加入 Allowed Callback URLs 与 Allowed Logout URLs
未将 handleRedirectCallback 包裹在 ngZone.run() 中：Angular 无法检测认证状态变化
使用 window.location.href 重定向登录：必须使用 Browser.open()
useRefreshTokens 未设为 true：移动端必需
useRefreshTokensFallback 未设为 false：必须为 false 以避免 iframe 回退刷新
缺少 @capacitor/app 深度链接监听：需 appUrlOpen 监听器
在移动端使用 loginWithPopup：原生不支持弹窗，应使用 loginWithRedirect
回调 URL 不匹配：URL scheme 必须与 capacitor.config.ts 中的 appId 完全一致

适用场景

适用于需要在 Ionic Angular + Capacitor 应用中集成 Auth0 认证的开发者。

限制与不适用场景

Ionic React 应用应使用 auth0-ionic-react
Ionic Vue 应用应使用 auth0-ionic-vue
纯浏览器 Angular SPA 应使用 auth0-angular 或 auth0-react
React Native（非 Ionic）应使用 auth0-react-native
Expo 应使用 auth0-expo
原生 iOS（Swift）应使用 auth0-swift
原生 Android（Kotlin）应使用 auth0-android

快速参考（API）

AuthService.loginWithRedirect(options)：启动登录流程，使用自定义 openUrl
AuthService.logout(options)：登出，使用自定义 openUrl 与 returnTo
AuthService.handleRedirectCallback(url)：处理来自深度链接的回调 URL
AuthService.isAuthenticated$：Observable boolean，用户是否已登录
AuthService.user$：Observable，当前用户资料
AuthService.isLoading$：Observable boolean，SDK 初始化状态
AuthService.error$：Observable，认证错误
AuthService.getAccessTokenSilently()：获取访问令牌（移动端使用刷新令牌）
Browser.open({ url })：在系统浏览器打开 URL（Capacitor）
CapApp.addListener('appUrlOpen', cb)：监听深度链接回调（Capacitor）

安全提示

技能要求绝不显示凭据：从 CLI 或文件获取 Auth0 凭据后，不要打印、回显或显示它们，应静默写入配置文件（src/environments/environment.ts）。

参考链接：Auth0 Angular SDK (GitHub)、Auth0 Ionic Angular Quickstart、Auth0 Angular SDK API Reference、Capacitor Browser Plugin、Capacitor App Plugin Deep Links、Ionic Framework Angular。

技能介绍

用途