auth0-nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Auth0 Next.js Integration

Auth0 Next.js 集成方案

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

使用@auth0/nextjs-auth0为Next.js应用添加认证功能，同时支持App Router和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

Next.js 13+版本的应用（支持App Router或Pages Router）
已完成配置的Auth0账号和应用
若尚未设置Auth0，请先使用
```
auth0-quickstart
```
技能

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

纯客户端React应用 - 对于Vite/CRA单页应用，请使用
```
auth0-react
```
React Native移动应用 - 针对iOS/Android平台，请使用
```
auth0-react-native
```
非Next.js框架 - 使用对应框架的专属SDK（Express、Vue、Angular等）
仅无状态API - 若无需会话管理，请使用JWT验证中间件

Quick Start Workflow

快速开始流程

1. Install SDK

1. 安装SDK

bash

npm install @auth0/nextjs-auth0

bash

npm install @auth0/nextjs-auth0

2. Configure Environment

2. 配置环境变量

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

For manual setup:

Create

.env.local

bash

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

.gitignore

使用Auth0 CLI自动配置，请查看设置指南获取完整脚本。

手动配置：

创建

.env.local

文件：

bash

AUTH0_SECRET=<生成32位字符的密钥>
APP_BASE_URL=http://localhost:3000
AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

生成密钥：

openssl rand -hex 32

重要提示： 将

.env.local

添加至

.gitignore

文件中

3. Create Auth0 Client and Middleware

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

Create

lib/auth0.ts

typescript

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:

typescript

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):

typescript

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:

typescript

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

创建

lib/auth0.ts

文件：

typescript

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 vs 16）：

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

middleware.ts

：

typescript

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配置一致）：

typescript

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

：

typescript

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. Add User Context (Optional)

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

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

typescript

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

typescript

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>
  );
}

注意： 在v4版本中，无需强制使用

<Auth0Provider>

包裹应用。仅当需要在服务端渲染时将初始用户信息传递给

useUser()

时才需要配置。

App Router - 可选择在

app/layout.tsx

中包裹应用：

typescript

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

中包裹应用：

typescript

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

5. 添加认证UI组件

Client Component (works in both routers):

typescript

'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>;
}

客户端组件（同时支持两种路由）：

typescript

'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. Test Authentication

6. 测试认证流程

Start your dev server:

bash

npm run dev

Visit

http://localhost:3000

and test the login flow.

启动开发服务器：

bash

npm run dev

访问

http://localhost:3000

并测试登录流程。

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

设置指南 - 自动配置脚本、环境变量配置、Auth0 CLI使用说明
集成指南 - 服务端认证、受保护路由、API路由、中间件
API参考 - 完整SDK API、钩子函数、辅助工具、会话管理

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 `auth0.middleware()`
Wrong route paths	v4 uses `/auth/login` not `/api/auth/login` - routes drop the `/api` prefix
Missing or weak AUTH0_SECRET	Generate secure secret with `openssl rand -hex 32` and store in .env.local
Using .env instead of .env.local	Next.js requires .env.local for local secrets, and .env.local should be in .gitignore
App created as SPA type in Auth0	Must be Regular Web Application type for Next.js
Using removed v3 helpers	v4 removed `withPageAuthRequired` and `withApiAuthRequired` - use `getSession()` instead
Using useUser in Server Component	useUser is client-only, use `auth0.getSession()` for Server Components
AUTH0_DOMAIN includes https://	v4 `AUTH0_DOMAIN` should be just the domain (e.g., `example.auth0.com` ), no scheme

错误	修复方案
使用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版本需要中间件来挂载认证路由 - 创建 `middleware.ts` （Next.js 15和16通用）或 `proxy.ts` （仅Next.js 16可用）并调用 `auth0.middleware()`
路由路径错误	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` ），不包含协议头

Related Skills

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

V4版本设置要点：

创建
```
lib/auth0.ts
```
并实例化
```
Auth0Client
```
必须配置中间件：
- Next.js 15：创建
```
middleware.ts
```
  并实现
```
middleware()
```
  函数
- Next.js 16：创建
```
middleware.ts
```
  实现
```
middleware()
```
  函数或创建
```
proxy.ts
```
  实现
```
proxy()
```
  函数
可选：使用
```
<Auth0Provider>
```
包裹应用以支持服务端渲染用户信息

客户端钩子函数：

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

服务端方法：

```
auth0.getSession()
```
- 在服务端组件/API路由/中间件中获取会话信息
```
auth0.getAccessToken()
```
- 获取调用API所需的访问令牌

常见使用场景：

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

auth0-nextjs

Original

Translation

Auth0 Next.js Integration

Auth0 Next.js 集成方案

Prerequisites

前置条件

When NOT to Use

不适用场景

Quick Start Workflow

快速开始流程

1. Install SDK

1. 安装SDK

2. Configure Environment

2. 配置环境变量

3. Create Auth0 Client and Middleware

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

4. Add User Context (Optional)

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

5. Add Authentication UI

5. 添加认证UI组件

6. Test Authentication

6. 测试认证流程

Detailed Documentation

详细文档

Common Mistakes

常见错误

Related Skills

相关技能

Quick Reference

快速参考

References

参考链接