auth0-vue

Auth0 Vue.js 集成

使用 @auth0/auth0-vue 为 Vue.js 3 单页应用添加身份验证。

---

前提条件

• Vue 3+ 应用（Vite 或 Vue CLI）
• 已配置 Auth0 账户和应用
• 如果尚未设置 Auth0，请先使用 auth0-quickstart 技能

不适用场景

• 服务端渲染的 Vue 应用 - 有关 SSR 模式，请参阅 Auth0 Nuxt.js 指南
• Vue 2 应用 - 此 SDK 需要 Vue 3+，请使用旧版 @auth0/auth0-spa-js 封装
• 嵌入式登录 - 此 SDK 使用 Auth0 Universal Login（基于重定向）
• 后端 API 身份验证 - 请改用 express-openid-connect 或 JWT 验证

---

快速入门工作流

1. 安装 SDK

npm install @auth0/auth0-vue

2. 配置环境

如需通过 Auth0 CLI 自动设置，请参阅设置指南获取完整脚本。

手动设置：

创建 .env 文件：

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

3. 配置 Auth0 插件

更新 src/main.ts：

import { createApp } from 'vue';
import { createAuth0 } from '@auth0/auth0-vue';
import App from './App.vue';

const app = createApp(App);

app.use(
  createAuth0({
    domain: import.meta.env.VITE_AUTH0_DOMAIN,
    clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
    authorizationParams: {
      redirect_uri: window.location.origin
    }
  })
);

app.mount('#app');

4. 添加身份验证 UI

创建登录组件：

<script setup lang="ts">
import { useAuth0 } from '@auth0/auth0-vue';

const { loginWithRedirect, logout, isAuthenticated, user, isLoading } = useAuth0();
</script>

<template>
  <div>
    <div v-if="isLoading">Loading...</div>

    <div v-else-if="isAuthenticated">
      <img :src="user?.picture" :alt="user?.name" />
      <span>Welcome, {{ user?.name }}</span>
      <button @click="logout({ logoutParams: { returnTo: window.location.origin }})">
        Logout
      </button>
    </div>

    <button v-else @click="loginWithRedirect()">
      Login
    </button>
  </div>
</template>

5. 测试身份验证

启动开发服务器并测试登录流程：

npm run dev

---

详细文档

• 设置指南 - 自动设置脚本（Bash/PowerShell）、CLI 命令、手动配置
• 集成指南 - 受保护的路由、API 调用、错误处理、组合式函数
• API 参考 - 完整的 SDK API、配置选项、组合式函数参考、测试策略

---

常见错误

错误	修复方法
忘记在 Auth0 Dashboard 中添加重定向 URI	在 Auth0 Dashboard 的 Allowed Callback URLs 中添加应用 URL（例如，http://localhost:3000、https://app.example.com）
使用了错误的环境变量前缀	Vite 要求使用 VITE_ 前缀，Vue CLI 使用 VUE_APP_
未处理加载状态	渲染依赖身份验证的 UI 前，始终检查 isLoading
将令牌存储在 localStorage 中	切勿手动存储令牌 — SDK 会自动安全存储
未注册 createAuth0 插件	必须在挂载应用前调用 app.use(createAuth0({...}))
插件加载前访问身份验证信息	将依赖身份验证的代码放在 v-if="!isLoading" 中

---

相关技能

• auth0-quickstart - Auth0 基本设置
• auth0-migration - 从其他身份验证提供商迁移
• auth0-mfa - 添加多因素身份验证
• auth0-dpop - 添加 DPoP 设备绑定令牌绑定
• auth0-cli - 从终端管理 Auth0 资源

---

快速参考

核心组合式函数：

• useAuth0() - 主要身份验证组合式函数
• isAuthenticated - 响应式检查用户是否已登录
• user - 响应式用户资料信息
• loginWithRedirect() - 发起登录
• logout() - 将用户登出
• getAccessTokenSilently() - 获取用于 API 调用的访问令牌

DPoP 组合式函数（需要在 createAuth0 配置中设置 useDpop: true — 请参阅 auth0-dpop）：

• createFetcher(config) - 返回一个支持 DPoP、兼容 fetch 的函数
• generateDpopProof(params) - 手动生成 DPoP 证明 JWT
• getDpopNonce(id?) - 获取当前存储的 DPoP nonce
• setDpopNonce(nonce, id?) - 存储服务器签发的 DPoP nonce

常见用例：

• 登录/登出按钮 → 请参阅上文步骤 4
• 使用导航守卫保护路由 → 集成指南
• 使用令牌调用 API → 集成指南
• 错误处理 → 集成指南

---

参考资料

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