auth0-nuxt

Auth0 Nuxt SDK

概述

适用于 Nuxt 3/4 的服务端会话身份验证。与 @auth0/auth0-vue（客户端 SPA）不同。

核心原则： 使用服务端加密 Cookie 会话，而非客户端令牌。

适用场景

在以下情况下使用：

• 构建使用服务端渲染的 Nuxt 3/4 应用（Node.js 20 LTS+）
• 需要通过加密 Cookie 安全地管理会话
• 保护服务端路由和 API 端点
• 访问 Auth0 Management API 或自定义 API

在以下情况下不要使用：

• 使用 Nuxt 2（不受支持，请使用其他 Auth0 SDK）
• 构建没有服务端的纯客户端 SPA（请改用 @auth0/auth0-vue）
• 使用非 Auth0 身份验证提供商
• 仅进行静态站点生成（SSG），没有服务端运行时

需要避免的关键错误

错误	解决方案
安装 @auth0/auth0-vue 或 @auth0/auth0-spa-js	使用 @auth0/auth0-nuxt
Auth0 应用类型为 "Single Page Application"	使用 "Regular Web Application"
环境变量：VITE_AUTH0_* 或 VUE_APP_AUTH0_*	使用 NUXT_AUTH0_* 前缀
使用 useUser() 进行安全检查	在服务端使用 useAuth0(event).getSession()
Auth0 Dashboard 中缺少回调 URL	添加 http://localhost:3000/auth/callback
会话密钥强度不足或缺失	生成密钥：openssl rand -hex 64
在 nuxt.config.ts 中硬编码凭据	将 runtimeConfig 值留空；Nuxt 会从 NUXT_AUTH0_* 环境变量自动填充

快速设置

# 1. Install
npm install @auth0/auth0-nuxt

# 2. Generate secret
openssl rand -hex 64

# 3. .env
NUXT_AUTH0_DOMAIN=your-tenant.auth0.com
NUXT_AUTH0_CLIENT_ID=your-client-id
NUXT_AUTH0_CLIENT_SECRET=your-client-secret
NUXT_AUTH0_SESSION_SECRET=<from-openssl>
NUXT_AUTH0_APP_BASE_URL=http://localhost:3000
NUXT_AUTH0_AUDIENCE=https://your-api  # optional

// 4. nuxt.config.ts
// Leave values as empty strings — Nuxt auto-fills them from NUXT_AUTH0_* env vars at runtime.
// If you prefer explicit mapping, use: domain: process.env.NUXT_AUTH0_DOMAIN || ''
export default defineNuxtConfig({
  modules: ['@auth0/auth0-nuxt'],
  runtimeConfig: {
    auth0: {
      domain: '',
      clientId: '',
      clientSecret: '',
      sessionSecret: '',
      appBaseUrl: 'http://localhost:3000',
      audience: '',  // optional
    },
  },
})

内置路由

SDK 会自动挂载以下路由：

路由	方法	用途
/auth/login	GET	启动登录流程。支持 ?returnTo=/path 参数
/auth/callback	GET	处理登录后的 Auth0 回调
/auth/logout	GET	将用户登出并重定向至 Auth0 登出页面
/auth/backchannel-logout	POST	接收用于后端通道登出的登出令牌

自定义： 向模块配置传入 routes: { login, callback, logout, backchannelLogout } 或 mountRoutes: false。

组合式函数

组合式函数	上下文	用法
useAuth0(event)	服务端	访问 getUser()、getSession()、getAccessToken()、logout()
useUser()	客户端	仅用于显示用户数据。绝不可用于安全检查

// Server example
const auth0 = useAuth0(event);
const session = await auth0.getSession();

<script setup>
const user = useUser();
</script>

<template>
  <div v-if="user">Welcome {{ user.name }}</div>
<template>

保护路由

三个层级： 路由中间件（客户端）、服务端中间件（SSR）、API 守卫。

// middleware/auth.ts - Client navigation
export default defineNuxtRouteMiddleware((to) => {
  if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
});

// server/middleware/auth.server.ts - SSR protection
export default defineEventHandler(async (event) => {
  const url = getRequestURL(event);
  const auth0Client = useAuth0(event);
  const session = await auth0Client.getSession();
  if (!session)  {
    return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
  }
});

// server/api/protected.ts - API endpoint protection
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const session = await auth0Client.getSession();

  if (!session) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Unauthorized'
    });
  }

  return { data: 'protected data' };
});

有关基于角色、基于权限和高级用法： route-protection.md

会话管理

无状态（默认）

使用加密、分块 Cookie。无需配置。

有状态（Redis、MongoDB 等）

适用于较大的会话或分布式系统：

// nuxt.config.ts
modules: [
  ['@auth0/auth0-nuxt', {
    sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
  }]
]

完整的会话存储实现请参阅： session-stores.md

API 集成

配置 API 访问令牌的 audience：

// nuxt.config.ts
runtimeConfig: {
  auth0: {
    audience: 'https://your-api-identifier',
  }
}

在服务端获取令牌：

// server/api/call-api.ts
export default defineEventHandler(async (event) => {
  const auth0Client = useAuth0(event);
  const { accessToken } = await auth0Client.getAccessToken();

  return await $fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });
});

安全检查清单

• ✅ 仅进行服务端验证（绝不信任 useUser()）
• ✅ 在生产环境中使用 HTTPS
• ✅ 使用强会话密钥（openssl rand -hex 64）
• ✅ 绝不提交 .env 文件
• ✅ 对 PII/大型数据使用有状态会话

故障排除

错误	解决方案
"Module not found"	安装 @auth0/auth0-nuxt，而非 @auth0/auth0-vue
"Missing domain/clientId/clientSecret"	检查 NUXT_AUTH0_ 前缀、.env 位置和 runtimeConfig
"Redirect URI mismatch"	确保 Auth0 Dashboard 中的回调地址与 appBaseUrl + /auth/callback 一致
"useAuth0 is not defined"	仅在服务端上下文中使用，并传入 H3 event 对象
Cookie 过大	使用有状态会话或减少作用域

更多资源

指南： 路由保护模式 • 自定义会话存储 • 常见示例

相关技能

• auth0-quickstart - Auth0 基础设置
• auth0-cli - 在终端中管理 Auth0 资源

---

链接： Auth0-Nuxt GitHub • Auth0 文档 • Nuxt 模块