Auth0 Next.js 身份验证集成教程 - 支持App Router和Pages Router

auth0-nextjs by auth0/agent-skills

498 周安装量

13 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/auth0/agent-skills --skill auth0-nextjs

开发 JavaScript 框架安全

🇨🇳中文介绍

Auth0 Next.js 集成

使用 @auth0/nextjs-auth0 为 Next.js 应用程序添加身份验证。同时支持 App Router 和 Pages Router。

先决条件

Next.js 13+ 应用程序（App Router 或 Pages Router）
已配置的 Auth0 账户和应用程序
如果您尚未设置 Auth0，请先使用 auth0-quickstart 技能

何时不应使用

仅限客户端的 React 应用 - 对于 Vite/CRA SPA，请使用 auth0-react
React Native 移动应用 - 对于 iOS/Android，请使用 auth0-react-native
非 Next.js 框架 - 使用特定于框架的 SDK（Express、Vue、Angular 等）
仅限无状态 API - 如果不需要会话管理，请使用 JWT 验证中间件

快速开始工作流程

1. 安装 SDK

npm install @auth0/nextjs-auth0

2. 配置环境

对于使用 Auth0 CLI 的自动化设置，请参阅获取完整脚本。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

3. 创建 Auth0 客户端和中间件

创建 lib/auth0.ts：

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

中间件配置（Next.js 15 与 16）：

Next.js 15 - 在项目根目录创建 middleware.ts：

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - 您有两个选择：

选项 1： 使用 middleware.ts（与 Next.js 15 相同）：

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

选项 2： 在项目根目录使用 proxy.ts：

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

这将自动创建以下端点：

/auth/login - 登录
/auth/logout - 登出
/auth/callback - OAuth 回调
/auth/profile - 用户资料

4. 添加用户上下文（可选）

注意： 在 v4 中，使用 <Auth0Provider> 包装是可选的。仅当您希望在服务器渲染期间将初始用户传递给 useUser() 时才需要。

App Router - 可选择在 app/layout.tsx 中包装应用：

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import { auth0 } from './lib/auth0';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </html>
  );
}

Pages Router - 可选择在 pages/_app.tsx 中包装应用：

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </Auth0Provider>
  );
}

5. 添加身份验证 UI

客户端组件（适用于两种路由器）：

'use client'; // 仅 App Router 需要

import { useUser } from '@auth0/nextjs-auth0/client';

export default function Profile() {
  const { user, isLoading } = useUser();

  if (isLoading) return <div>加载中...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>欢迎，{user.name}！</h2>
        <a href="/auth/logout">登出</a>
      </div>
    );
  }

  return <a href="/auth/login">登录</a>;
}

6. 测试身份验证

启动开发服务器：

访问 http://localhost:3000 并测试登录流程。

设置指南 - 自动化设置脚本、环境配置、Auth0 CLI 使用
集成指南 - 服务器端身份验证、受保护路由、API 路由、中间件
API 参考 - 完整的 SDK API、钩子、辅助函数、会话管理

错误	修复方法
使用 v3 环境变量	v4 使用 `APP_BASE_URL` 和 `AUTH0_DOMAIN`（而不是 `AUTH0_BASE_URL` 或 `AUTH0_ISSUER_BASE_URL`）
忘记在 Auth0 仪表板中添加回调 URL	将 `/auth/callback` 添加到允许的回调 URL（例如，`http://localhost:3000/auth/callback`）
缺少中间件配置	v4 需要中间件来挂载身份验证路由 - 创建包含 `auth0.middleware()` 的 `middleware.ts`（Next.js 15+16）或 `proxy.ts`（仅 Next.js 16）
路由路径错误	v4 使用 `/auth/login` 而不是 `/api/auth/login` - 路由去掉了 `/api` 前缀
缺少或强度不足的 AUTH0_SECRET	使用 `openssl rand -hex 32` 生成安全密钥并存储在 .env.local 中
使用 .env 而不是 .env.local	Next.js 要求使用 .env.local 存储本地密钥，并且 .env.local 应位于 .gitignore 中
在 Auth0 中创建为 SPA 类型	Next.js 必须使用常规 Web 应用程序类型
使用已移除的 v3 辅助函数	v4 移除了 `withPageAuthRequired` 和 `withApiAuthRequired` - 改用 `getSession()`
在服务器组件中使用 useUser	useUser 仅限客户端使用，对于服务器组件请使用 `auth0.getSession()`
AUTH0_DOMAIN 包含 https://	v4 的 `AUTH0_DOMAIN` 应仅为域名（例如，`example.auth0.com`），不包含协议

auth0-quickstart - 基础 Auth0 设置
auth0-migration - 从其他身份验证提供商迁移
auth0-mfa - 添加多因素身份验证

使用 Auth0Client 实例创建 lib/auth0.ts
创建中间件配置（必需）：
- Next.js 15：包含 middleware() 函数的 middleware.ts
- Next.js 16：包含 middleware() 函数的 middleware.ts 或包含 proxy() 函数的 proxy.ts
可选：使用 <Auth0Provider> 包装以支持 SSR 用户

客户端钩子：

useUser() - 在客户端组件中获取用户
user - 用户资料对象
isLoading - 加载状态

服务器端方法：

auth0.getSession() - 在服务器组件/API 路由/中间件中获取会话
auth0.getAccessToken() - 获取用于调用 API 的访问令牌

登录/登出链接 → 使用 /auth/login 和 /auth/logout 路径（参见步骤 5）
受保护页面（App Router） → 集成指南
受保护页面（Pages Router） → 集成指南
带身份验证的 API 路由 → 集成指南
中间件保护 → 集成指南

🇺🇸English

Auth0 Next.js Integration

Add authentication to Next.js applications using @auth0/nextjs-auth0. Supports both App Router and Pages Router.

Prerequisites

Next.js 13+ application (App Router or Pages Router)
Auth0 account and application configured
If you don't have Auth0 set up yet, use the auth0-quickstart skill first

When NOT to Use

Client-side only React apps - Use auth0-react for Vite/CRA SPAs
React Native mobile apps - Use auth0-react-native for iOS/Android
Non-Next.js frameworks - Use framework-specific SDKs (Express, Vue, Angular, etc.)
Stateless APIs only - Use JWT validation middleware if you don't need session management

Quick Start Workflow

1. Install SDK

npm install @auth0/nextjs-auth0

2. Configure Environment

For automated setup with Auth0 CLI , see Setup Guide for complete scripts.

For manual setup:

Create .env.local:

AUTH0_SECRET=<generate-a-32-character-secret>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

Generate secret: openssl rand -hex 32

Important: Add .env.local to .gitignore

3. Create Auth0 Client and Middleware

Create lib/auth0.ts:

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL!,
});

Middleware Configuration (Next.js 15 vs 16):

Next.js 15 - Create middleware.ts at project root:

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Next.js 16 - You have two options:

Option 1: Use middleware.ts (same as Next.js 15):

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

Option 2: Use proxy.ts at project root:

import { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)',
  ],
};

This automatically creates endpoints:

/auth/login - Login
/auth/logout - Logout
/auth/callback - OAuth callback
/auth/profile - User profile

4. Add User Context (Optional)

Note: In v4, wrapping with <Auth0Provider> is optional. Only needed if you want to pass an initial user during server rendering to useUser().

App Router - Optionally wrap app in app/layout.tsx:

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import { auth0 } from './lib/auth0';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await auth0.getSession();

  return (
    <html>
      <body>
        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
      </body>
    </html>
  );
}

Pages Router - Optionally wrap app in pages/_app.tsx:

import { Auth0Provider } from '@auth0/nextjs-auth0/client';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <Auth0Provider user={pageProps.user}>
      <Component {...pageProps} />
    </Auth0Provider>
  );
}

5. Add Authentication UI

Client Component (works in both routers):

'use client'; // Only needed for App Router

import { useUser } from '@auth0/nextjs-auth0/client';

export default function Profile() {
  const { user, isLoading } = useUser();

  if (isLoading) return <div>Loading...</div>;

  if (user) {
    return (
      <div>
        <img src={user.picture} alt={user.name} />
        <h2>Welcome, {user.name}!</h2>
        <a href="/auth/logout">Logout</a>
      </div>
    );
  }

  return <a href="/auth/login">Login</a>;
}

6. Test Authentication

Start your dev server:

npm run dev

Visit http://localhost:3000 and test the login flow.

Detailed Documentation

Setup Guide - Automated setup scripts, environment configuration, Auth0 CLI usage
Integration Guide - Server-side auth, protected routes, API routes, middleware
API Reference - Complete SDK API, hooks, helpers, session management

Common Mistakes

Mistake	Fix
Using v3 environment variables	v4 uses `APP_BASE_URL` and `AUTH0_DOMAIN` (not `AUTH0_BASE_URL` or `AUTH0_ISSUER_BASE_URL`)
Forgot to add callback URL in Auth0 Dashboard	Add `/auth/callback` to Allowed Callback URLs (e.g., `http://localhost:3000/auth/callback`)
Missing middleware configuration	v4 requires middleware to mount auth routes - create `middleware.ts` (Next.js 15+16) or `proxy.ts` (Next.js 16 only) with

Related Skills

auth0-quickstart - Basic Auth0 setup
auth0-migration - Migrate from another auth provider
auth0-mfa - Add Multi-Factor Authentication

Quick Reference

V4 Setup:

Create lib/auth0.ts with Auth0Client instance
Create middleware configuration (required):
- Next.js 15: middleware.ts with middleware() function
- Next.js 16: middleware.ts with middleware() OR proxy.ts with proxy() function
Optional: Wrap with <Auth0Provider> for SSR user

Client-Side Hooks:

useUser() - Get user in client components
user - User profile object
isLoading - Loading state

Server-Side Methods:

auth0.getSession() - Get session in Server Components/API routes/middleware
auth0.getAccessToken() - Get access token for calling APIs

Common Use Cases:

Login/Logout links → Use /auth/login and /auth/logout paths (see Step 5)
Protected pages (App Router) → Integration Guide
Protected pages (Pages Router) → Integration Guide
API routes with auth → Integration Guide
Middleware protection → Integration Guide

References

Weekly Installs

269

Repository

auth0/agent-skills

GitHub Stars

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode256

codex255

github-copilot250

gemini-cli248

amp243

kimi-cli243

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

auth0.middleware()