auth0-ionic-vue
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAuth0 Ionic Vue (Capacitor) Integration
Auth0 Ionic Vue(Capacitor)集成
Add Auth0 authentication to Ionic Vue applications using Capacitor. This skill covers native mobile authentication using the SDK combined with and plugins for deep link handling on iOS and Android.
@auth0/auth0-vue@capacitor/browser@capacitor/app为使用Capacitor的Ionic Vue应用添加Auth0认证功能。本技能介绍如何结合 SDK与、插件,实现iOS和Android端的原生移动认证及深度链接处理。
@auth0/auth0-vue@capacitor/browser@capacitor/appPrerequisites
前提条件
- Node.js 18+
- Ionic CLI ()
npm install -g @ionic/cli - An existing Ionic Vue application with Capacitor configured
- Auth0 account and tenant
- For iOS: Xcode 14+ and CocoaPods
- For Android: Android Studio with API level 21+
- Auth0 CLI —
brew install auth0/auth0-cli/auth0
- Node.js 18+
- Ionic CLI(执行安装)
npm install -g @ionic/cli - 已配置Capacitor的现有Ionic Vue应用
- Auth0账户和租户
- iOS环境:Xcode 14+ 及 CocoaPods
- Android环境:API等级21+的Android Studio
- Auth0 CLI — 执行安装
brew install auth0/auth0-cli/auth0
When NOT to Use
不适用场景
| Use Case | Recommended Skill |
|---|---|
| Vue SPA (no Capacitor/Ionic) | |
| React SPA (no Capacitor/Ionic) | |
| React Native (bare CLI) | |
| Expo (React Native) | |
| Ionic + React + Capacitor | |
| Ionic + Angular + Capacitor | |
| Next.js (server-side) | |
| Nuxt (server-side) | |
| iOS native (Swift) | |
| Android native (Kotlin) | |
| 使用场景 | 推荐技能 |
|---|---|
| Vue单页应用(无Capacitor/Ionic) | |
| React单页应用(无Capacitor/Ionic) | |
| React Native(原生CLI) | |
| Expo(React Native) | |
| Ionic + React + Capacitor | |
| Ionic + Angular + Capacitor | |
| Next.js(服务端) | |
| Nuxt(服务端) | |
| iOS原生(Swift) | |
| Android原生(Kotlin) | |
Quick Start Workflow
快速开始流程
Step 1: Configure Auth0
步骤1:配置Auth0
For automated setup with Auth0 CLI, see Setup Guide for complete scripts.
For manual setup, configure a Native application in the Auth0 Dashboard and note your Domain and Client ID.
使用Auth0 CLI自动配置,请查看设置指南获取完整脚本。
手动配置,在Auth0控制台中配置一个Native应用,并记录你的域名(Domain)和客户端ID(Client ID)。
Step 2: Install Dependencies
步骤2:安装依赖
bash
npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
npx cap syncbash
npm install @auth0/auth0-vue @capacitor/browser @capacitor/app
npx cap syncStep 3: Set Up Auth0 Plugin
步骤3:设置Auth0插件
Agent instruction: If Step 1 already wroteand updated.env, verify the configuration looks correct and skip to Step 4. Only use the template below if configuring manually.src/main.ts
Register the Auth0 Vue plugin in your app entry point (), configuring it for Capacitor. Credentials are read from via :
src/main.ts.envimport.meta.envtypescript
import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';
// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";
const app = createApp(App);
app.use(IonicVue);
app.use(router);
app.use(
createAuth0({
domain: import.meta.env.VITE_AUTH0_DOMAIN,
clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
useRefreshTokens: true,
useRefreshTokensFallback: false,
authorizationParams: {
redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
}
})
);
router.isReady().then(() => {
app.mount('#app');
});Agent说明: 如果步骤1已生成并更新.env,请验证配置是否正确,然后跳至步骤4。仅在手动配置时使用以下模板。src/main.ts
在应用入口文件中注册Auth0 Vue插件,并针对Capacitor进行配置。通过从读取凭证:
src/main.tsimport.meta.env.envtypescript
import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import { IonicVue } from '@ionic/vue';
import App from './App.vue';
import router from './router';
// Agent:从capacitor.config.ts读取appId并替换此值
const packageId = "YOUR_PACKAGE_ID";
const app = createApp(App);
app.use(IonicVue);
app.use(router);
app.use(
createAuth0({
domain: import.meta.env.VITE_AUTH0_DOMAIN,
clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
useRefreshTokens: true,
useRefreshTokensFallback: false,
authorizationParams: {
redirect_uri: `${packageId}://${import.meta.env.VITE_AUTH0_DOMAIN}/capacitor/${packageId}/callback`
}
})
);
router.isReady().then(() => {
app.mount('#app');
});Step 4: Implement Login with Capacitor Browser
步骤4:通过Capacitor Browser实现登录
vue
<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';
const { loginWithRedirect } = useAuth0();
const login = async () => {
await loginWithRedirect({
async openUrl(url: string) {
await Browser.open({ url, windowName: "_self" });
}
});
};
</script>
<template>
<ion-button @click="login">Log in</ion-button>
</template>vue
<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';
const { loginWithRedirect } = useAuth0();
const login = async () => {
await loginWithRedirect({
async openUrl(url: string) {
await Browser.open({ url, windowName: "_self" });
}
});
};
</script>
<template>
<ion-button @click="login">登录</ion-button>
</template>Step 5: Handle Callback via Deep Link
步骤5:通过深度链接处理回调
Handle the deep link callback in your App.vue component. This must run on app initialization:
vue
<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';
const { handleRedirectCallback } = useAuth0();
let urlOpenListener: any;
onMounted(async () => {
urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
await handleRedirectCallback(url);
}
await Browser.close();
});
});
onUnmounted(() => {
urlOpenListener?.remove();
});
</script>
<template>
<ion-app>
<ion-router-outlet />
</ion-app>
</template>在App.vue组件中处理深度链接回调,此逻辑必须在应用初始化时运行:
vue
<script setup lang="ts">
import { onMounted, onUnmounted } from 'vue';
import { useAuth0 } from '@auth0/auth0-vue';
import { App as CapApp } from '@capacitor/app';
import { Browser } from '@capacitor/browser';
import { IonApp, IonRouterOutlet } from '@ionic/vue';
const { handleRedirectCallback } = useAuth0();
let urlOpenListener: any;
onMounted(async () => {
urlOpenListener = await CapApp.addListener('appUrlOpen', async ({ url }) => {
if (url.includes('state') && (url.includes('code') || url.includes('error'))) {
await handleRedirectCallback(url);
}
await Browser.close();
});
});
onUnmounted(() => {
urlOpenListener?.remove();
});
</script>
<template>
<ion-app>
<ion-router-outlet />
</ion-app>
</template>Step 6: Implement Logout
步骤6:实现登出功能
vue
<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';
const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent: read appId from capacitor.config.ts and replace this value
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
const { logout } = useAuth0();
const doLogout = async () => {
await logout({
logoutParams: {
returnTo: logoutUri
},
async openUrl(url: string) {
await Browser.open({ url, windowName: "_self" });
}
});
};
</script>
<template>
<ion-button @click="doLogout">Log out</ion-button>
</template>vue
<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';
import { Browser } from '@capacitor/browser';
import { IonButton } from '@ionic/vue';
const domain = import.meta.env.VITE_AUTH0_DOMAIN;
// Agent:从capacitor.config.ts读取appId并替换此值
const packageId = "YOUR_PACKAGE_ID";
const logoutUri = `${packageId}://${domain}/capacitor/${packageId}/callback`;
const { logout } = useAuth0();
const doLogout = async () => {
await logout({
logoutParams: {
returnTo: logoutUri
},
async openUrl(url: string) {
await Browser.open({ url, windowName: "_self" });
}
});
};
</script>
<template>
<ion-button @click="doLogout">登出</ion-button>
</template>Step 7: Build and Test
步骤7:构建并测试
Agent instruction: After integration, verify the build:bashionic build npx cap syncFor iOS:then build in Xcode. For Android:npx cap open iosthen build in Android Studio. If the build fails, iterate up to 5-6 times to fix issues. If still failing, usenpx cap open androidto request help.AskUserQuestion
Agent说明: 集成完成后,验证构建:bashionic build npx cap synciOS平台:执行后在Xcode中构建。 Android平台:执行npx cap open ios后在Android Studio中构建。 如果构建失败,可尝试修复5-6次。若仍失败,使用npx cap open android请求帮助。AskUserQuestion
Detailed Documentation
详细文档
- Setup Guide — Auth0 CLI automated setup (login, app creation, credential injection), Capacitor URL scheme registration, secret management
- Integration Patterns — Login/logout with Capacitor Browser, deep link callback handling, user profile, protected routes, token access, error handling
- Testing & Reference — Full API reference for createAuth0 options, useAuth0 composable, Capacitor plugin configuration, testing checklist, common issues
- 设置指南 — Auth0 CLI自动配置(登录、应用创建、凭证注入)、Capacitor URL scheme注册、密钥管理
- 集成模式 — 基于Capacitor Browser的登录/登出、深度链接回调处理、用户信息、受保护路由、令牌访问、错误处理
- 测试与参考 — createAuth0选项、useAuth0组合式函数、Capacitor插件配置的完整API参考、测试清单、常见问题
Common Mistakes
常见错误
| Mistake | Fix |
|---|---|
| App type not set to Native in Auth0 Dashboard | Change application type to "Native" in Dashboard settings |
| Missing or incorrect callback URL format | Use |
| Not enabling refresh tokens | Set |
Missing | Install both: |
| Not handling deep link callback | Add |
Forgetting | Always run |
Using | Use the custom URL scheme ( |
| Missing Allowed Origins in Dashboard | Add |
Not calling | Register Auth0 plugin before calling |
Accessing | |
| localStorage treated as persistent on mobile | Use refresh tokens ( |
| 错误 | 修复方案 |
|---|---|
| Auth0控制台中应用类型未设置为Native | 在控制台设置中将应用类型改为“Native” |
| 回调URL格式缺失或错误 | 使用 |
| 未启用刷新令牌 | 在 |
缺少 | 安装两者: |
| 未处理深度链接回调 | 添加 |
安装后忘记执行 | 安装Capacitor插件后务必执行 |
使用 | 使用自定义URL scheme( |
| 控制台中缺少允许的源 | 将 |
在挂载前未调用 | 在调用 |
错误地访问auth引用的 | |
| 将localStorage视为移动端持久存储 | 使用刷新令牌( |
WebAuth Method
WebAuth方法
This SDK uses Auth0's Universal Login (WebAuth) via the Capacitor Browser plugin. The method opens the Auth0 authorization endpoint in a system browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android). After authentication, Auth0 redirects back to the app using a native callback URL with a custom scheme: . The plugin captures this deep link, and processes the authorization code exchange.
loginWithRedirect(){packageId}://{domain}/capacitor/{packageId}/callback@capacitor/apphandleRedirectCallback(url)Unlike standard native SDKs that use or , Ionic Capacitor apps use the Capacitor-specific callback path with the package ID as the URL scheme.
https://{domain}/android/{packageId}/callbackhttps://{domain}/ios/{bundleId}/callback本SDK通过Capacitor Browser插件使用Auth0的通用登录(WebAuth)。方法在系统浏览器(iOS为SFSafariViewController,Android为Chrome Custom Tabs)中打开Auth0授权端点。认证完成后,Auth0通过带有自定义scheme的原生回调URL重定向回应用:。插件捕获此深度链接,处理授权码交换。
loginWithRedirect(){packageId}://{domain}/capacitor/{packageId}/callback@capacitor/apphandleRedirectCallback(url)与使用或的标准原生SDK不同,Ionic Capacitor应用使用Capacitor专属的回调路径,以包ID作为URL scheme。
https://{domain}/android/{packageId}/callbackhttps://{domain}/ios/{bundleId}/callbackRelated Skills
相关技能
- auth0-vue — Vue SPA (browser-only, no Capacitor)
- auth0-ionic-react — Ionic with React and Capacitor
- auth0-ionic-angular — Ionic with Angular and Capacitor
- auth0-react-native — React Native (bare CLI, no Ionic/Capacitor)
- auth0-expo — Expo (React Native) with Auth0
- auth0-vue — Vue单页应用(仅浏览器端,无Capacitor)
- auth0-ionic-react — Ionic结合React与Capacitor
- auth0-ionic-angular — Ionic结合Angular与Capacitor
- auth0-react-native — React Native(原生CLI,无Ionic/Capacitor)
- auth0-expo — Expo(React Native)结合Auth0
Quick Reference
快速参考
| API | Description |
|---|---|
| Vue plugin factory — registers Auth0 with |
| Composable — returns |
| Login via Universal Login — use |
| Logout — use |
| Process Auth0 callback URL from deep link |
| Get access token (uses refresh tokens on mobile) |
| Vue Router navigation guard factory for protected routes |
| Capacitor — opens URL in system browser (SFSafariViewController / Chrome Custom Tabs) |
| Capacitor — listens for deep link events |
| Capacitor — closes the in-app browser after callback |
| API | 描述 |
|---|---|
| Vue插件工厂 — 通过 |
| 组合式函数 — 返回 |
| 通过通用登录实现登录 — 在 |
| 登出 — 在 |
| 处理来自深度链接的Auth0回调URL |
| 获取访问令牌(移动端使用刷新令牌) |
| Vue Router导航守卫工厂,用于受保护路由 |
| Capacitor — 在系统浏览器中打开URL(SFSafariViewController / Chrome Custom Tabs) |
| Capacitor — 监听深度链接事件 |
| Capacitor — 回调后关闭内嵌浏览器 |