@auth0/nextjs-auth0

Auth0 Next.js SDK是一个用于在Next.js应用程序中执行用户认证的库.

📚 文档 - 🚀 开始 - 💻 API 参考 - 💬 反馈

文档

• 快速启动 - 我们的指南,将Auth0 添加到您的 Next.js 应用程序.
• 实例 - 很多例子 用于你不同的使用案例.
• 匿名会话 - 启用带有访问符和元数据的登录前身份.
• 警卫 - 一些重要的安全通知,你应该检查.
• Docs 站点 - 探索我们的文件网站 了解更多关于Auth0.

开始

1. 安装SDK

npm i @auth0/nextjs-auth0

这个库需要Node.js 20 LTS和较新的LTS版本.

2. 增加环境变量

将以下环境变量添加到您的 .env.local 文件 :

AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=
APP_BASE_URL= # optional for dynamic preview environments

这个 AUTH0_DOMAIN, (中文(简体) ), AUTH0_CLIENT_ID,以及 AUTH0_CLIENT_SECRET 可从 Auth0 剪贴板 一旦你创建了一个应用程序. 此申请必须是 Regular Web Application。 。 。 .

这个 AUTH0_SECRET 是用于加密会话和交易 cookie 的密钥。 您可以使用 openssl数字 :

openssl rand -hex 32

这个 APP_BASE_URL 您的应用程序正在运行的 URL 。 本地开发时,这种情况最为常见 http://localhost:3000。 。 。 . 如果您省略, SDK 会在运行时从收到的请求主机中推断出基础 URL .

[大
您需要在 Auth0 应用程序中通过 Auth0 剪贴板数字 :

• 添加 http://localhost:3000/auth/callback 名单 允许召回 URL
• 添加 http://localhost:3000 名单 允许登录 URL

当使用动态主机( 预览环境) 时, 请在 Auth0 应用程序中注册相应的调用和登录 URL .

动态基础 URL( 预览部署)

预览环境Vercel, (中文(简体) ), Netlify,可以省略 APP_BASE_URL 并让 SDK 在运行时从收到的请求主机中推断基础 URL 。 这使得动态预览 URL 在不附加配置的情况下工作 .

如果您知道启动时的基础 URL( 例如稳定生产域), 设置 appBaseUrl 或者说 APP_BASE_URL 到一个绝对的 URL。 不支持逗号分隔的值 .

由于主机头是不信任的输入,Auth0的"允许回调"URL是这个模式中的安全网:如果所推断的主机没有注册,Auth0拒绝授权请求.

示例(动力学):

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

export const auth0 = new Auth0Client();

示例(静态):

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

export const auth0 = new Auth0Client({
  appBaseUrl: "https://app.example.com"
});

[注]
在生产过程中依赖动态基站URL时,SDK会执行安全的cookie. 如果您明确设定 AUTH0_COOKIE_SECURE=false, (中文(简体) ), session.cookie.secure=false,或 transactionCookie.secure=false,SDK抛出 InvalidConfigurationError。 。 。 .

3. 创建 Auth0 SDK 客户端

创建 Auth0 客户端实例 。 此实例将被导入并用于任何您需要访问服务器上的认证方法的地方 .

将以下内容添加到命名的文件 lib/auth0.ts数字 :

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

export const auth0 = new Auth0Client();

[注] Auth0Client 自动使用安全默认来管理认证 cookie. 对于高级用例,可以通过提供自己的配置来自定义交易 cookie 行为. 见 交易 Cookie 配置 详细情况.

4. 添加认证中间软件

Next.js中的认证请求使用中间软件或代理文件在网络边界被截获.
根据您的 Next.js 版本, 跟踪下面的设置 .

\ 在下一个.js 15

创建一个 middleware.ts 在项目根中的文件 :

import type { NextRequest } from "next/server";

import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere

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

export const config = {
  matcher: [
    /*
     * Match all request paths except for:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"
  ]
};

[注]
如果你用一个 src/ 目录,该 middleware.ts 文件必须在 src/ 目录.

\ 在下一个.js 16

Next.js 16引入了名为代理.ts的新公约,取代了中件.ts. 这一变化更好地代表了网络截取边界,统一了请求处理 对于边缘和节点运行时间.

在工程的根部创建代理. ts文件( 或者将您现有的中间软件重命名为代理. ts) :

import { auth0 } from "./lib/auth0";

export async function proxy(request: Request) { // Note that proxy uses the standard Request type
  return await auth0.middleware(request);
}

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

[大
从开始 下一个.js 16,用于处理认证边界的建议文件为 proxy.ts。您仍可继续使用 middleware.ts 对于后向相容性,将在 边缘运行时间 在下一个.js 16. 然而,这是 已贬值 用于节点运行时间,并将在未来发布中被删除.

新的代理层也会在路由管中稍早地执行,以确保您的匹配器模式不会与其他代理或中间软件路径相冲突.

此外,边缘运行时间现在采用更严格的头和饼干验证,
因此避免设置非字符串饼干值或无效的标题格式.

[大 这个宽广的中件匹配器对于滚动会话和安全特性至关重要. 关于滚动会话停用时的情景,见 会话配置 备选办法.

您现在可以通过将用户重定向到您的应用程序来开始认证您的用户 /auth/login 路径 :

import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere

export default async function Home() {
  const session = await auth0.getSession();

  if (!session) {
    return (
      <main>
        <a href="/auth/login?screen_hint=signup">Sign up</a>
        <a href="/auth/login">Log in</a>
      </main>
    );
  }

  return (
    <main>
      <h1>Welcome, {session.user.name}!</h1>
    </main>
  );
}

[大
默认 <Link href="/auth/login"> 安全 —— SDK 检测 AUTO 前置信头并返回 204 No Content 没有写交易饼干。 避免 <Link href="/auth/login" prefetch={true}> (FullL preftch):它不会发送可被检测到的预取信头,因此SDK无法将其与真实的导航区分开来,并将开始登录流. 使用平面 <a> 标记或 <Link prefetch={false}> 如果您需要在所有预选模式中安全。 见 防止“ 431 请求标题字段太大” 出错 详细情况.

自定义客户端

您可以使用以下选项自定义客户端:

自定义 Auth 处理器

虽然认证路径由中间软件自动处理,但您仍然可以通过两种主要方法自定义认证流:

• 在认证处理器前运行自定义代码: 截取中间软件中的认证路由, 在认证动作前添加自定义逻辑
• 认证后运行代码: 使用 onCallback 认证完成后添加自定义逻辑的钩头

其他定制选项包括:

• 通过查询参数或静态配置登录参数
• 使用 beforeSessionSaved 钩子
• 使用查询参数登录重定向

[大 在自定义 auth 处理器时,总是验证用户输入(特别是重定向 URL),以防止安全漏洞,如打开重定向. 在可能的情况下使用相对的URL,并实施适当的输入消毒.

快速启动: 详细的例子和从v3逐步迁移的模式,见 自定义 Auth 处理器。 。 。 .

会话 Cookie 配置

您可以指定以下环境变量来配置会话 cookie :

AUTH0_COOKIE_DOMAIN=
AUTH0_COOKIE_PATH=
AUTH0_COOKIE_TRANSIENT=
AUTH0_COOKIE_SECURE=
AUTH0_COOKIE_SAME_SITE=
AUTH0_DPOP_PUBLIC_KEY=
AUTH0_DPOP_PRIVATE_KEY=
AUTH0_DPOP_CLOCK_SKEW=
AUTH0_DPOP_CLOCK_TOLERANCE=

DPop 配置

Auth0 下一个.js SDK 支持 DPoP( 证明 ) 用于加强OAuth 2.0安全。 DPoP将访问令牌绑定为密码密钥对,防止令牌被窃取并重放攻击.

快速启动

备选案文1:环境变量

# Enable DPoP and provide ES256 key pair
AUTH0_DPOP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----"
AUTH0_DPOP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQ...
-----END PRIVATE KEY-----"

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

export const auth0 = new Auth0Client({
  useDPoP: true
  // Keys loaded automatically from environment variables
});

备选案文2:程序配置

import { Auth0Client } from "@auth0/nextjs-auth0/server";
import { generateKeyPair } from "oauth4webapi";

const dpopKeyPair = await generateKeyPair("ES256");

export const auth0 = new Auth0Client({
  useDPoP: true,
  dpopKeyPair,
  dpopOptions: {
    clockTolerance: 30,  // Allow 30s clock difference
    retry: {
      delay: 100,        // 100ms retry delay
      jitter: true       // Add randomness
    }
  }
});

编写 DPOP 保护请求

// Create a fetcher - DPoP inherited from global configuration
const fetcher = await auth0.createFetcher(req, {
  baseUrl: "https://api.example.com"
  // useDPoP is inherited from Auth0Client config
});

// Make authenticated requests with automatic DPoP proof generation
const response = await fetcher.fetchWithAuth("/protected-resource", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ data: "example" })
});

DPoP 继承行为

创建于 createFetcher 从您自动继承全局 DPOP 配置 Auth0Client 举个例子.

这种继承模式遵循与Auth0-spa-js相同的行为,为Auth0 SDKs提供一致的开发者经验.

DPoP的完整文件、实例和最佳做法见 DPOP 实例。 。 。 .

高级: 时钟验证配置

为 DPop 证书配置时间验证, 以处理客户端和服务器之间的时钟差异 :

export const auth0 = new Auth0Client({
  useDPoP: true,
  dpopKeyPair: await generateKeyPair("ES256"),
  dpopOptions: {
    clockSkew: 120,      // Adjust for local clock being 2 minutes behind
    clockTolerance: 45   // Allow 45 seconds tolerance for validation
  }
});

或者通过环境变量配置 :

AUTH0_DPOP_CLOCK_SKEW=300        # Clock adjustment in seconds
AUTH0_DPOP_CLOCK_TOLERANCE=90    # Tolerance in seconds

客户配置中也有相应的对应方。 见 Cookie 配置 更多细节.

我的账户和我的组织的 API 代理处理器

SDK为Auth0的"My Account"和"My Organization Management API"提供内置代理支持,允许安全浏览器启动请求,同时维护服务器侧DPoP认证和令牌管理.

如何运作

代理处理器自动截取请求到 /me/* 财务报告和审定财务报表 /my-org/* 在 Next.js 应用程序中将路径转发给相应的 Auth0 API,并附有适当的认证头。 此执行后端的Frontend( BFF) 模式:

• 鼠标和 DPOP 密钥留在服务器上
• 访问符自动检索或刷新
• 为每个请求生成 DPop 证明
• 会话更新透明进行

配置

配置 API 的受众和范围 :

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

export const auth0 = new Auth0Client({
  useDPoP: true,
  authorizationParameters: {
    audience: "urn:your-api-identifier",
    scope: {
      [`https://${process.env.AUTH0_DOMAIN}/me/`]: "profile:read profile:write",
      [`https://${process.env.AUTH0_DOMAIN}/my-org/`]: "org:read org:write"
    }
  }
});

客户端用户端

通过代理路径提出请求 :

// My Account API
const response = await fetch("/me/v1/profile", {
  headers: { "scope": "profile:read" }
});

// My Organization API
const response = await fetch("/my-org/organizations", {
  headers: { "scope": "org:read" }
});

这个 scope 页眉指定了所需的范围。 SDK检索到一个有适当受众和范围的访问符,然后用认证头转发请求.

完整的文档、示例和与UI组件的集成模式,参见 我的账户和我的组织的 API 代理处理器。 。 。 .

基础路径

您的 Next.js 应用程序可能被配置为使用一个基础路径(例如: /dashboard)——这通常通过设置 basePath 选项 next.config.js 文档。 要配置 SDK 以使用基准路径, 您还需要设置 NEXT_PUBLIC_BASE_PATH 用于安装认证路径的环境变量.

例如,如果 NEXT_PUBLIC_BASE_PATH 环境变量设定为 /dashboard,SDK将挂载认证路径 /dashboard/auth/login, (中文(简体) ), /dashboard/auth/callback, (中文(简体) ), /dashboard/auth/profile等 (中文(简体) ).

[注] 我们不建议使用 NEXT_PUBLIC_BASE_PATH 环境变量与 APP_BASE_URL 包含路径组件。 如果您的应用程序被配置为使用基准路径, 您应该设置 APP_BASE_URL 转到应用程序的根 URL(例如: https://example.com并使用 NEXT_PUBLIC_BASE_PATH 指定基础路径的环境变量(例如: /dashboard) (中文(简体) ).

配置验证

SDK 在初始化时对所需的配置选项进行验证 Auth0Client。下列选项是强制性的,必须通过构建器选项或环境变量提供:

• domain (或 AUTH0_DOMAIN 环境变量)
• clientId (或 AUTH0_CLIENT_ID 环境变量)
• secret (或 AUTH0_SECRET 环境变量)
• 要么:
  • clientSecret (或 AUTH0_CLIENT_SECRET 环境变量),OR
  • clientAssertionSigningKey (或 AUTH0_CLIENT_ASSERTION_SIGNING_KEY 环境变量)

如果缺少其中任何需要的选项,SDK会发出警告并附上详细信息,解释缺少哪些选项以及如何提供.

appBaseUrl 是可选的;如果省略,SDK会在运行时从请求主机中推断出.

多个自定义域( MCD)

SDK支持用户针对同一租户上的多个Auth0自定义域进行认证. 传出 a DomainResolver 函数为 domain 选项以启用每个请求域解析 :

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

export const auth0 = new Auth0Client({
  domain: ({ headers }) => {
    const host = headers.get("host") ?? "";
    if (host.startsWith("brand1.")) return "auth.brand1.com";
    return "auth.default.com";
  }
});

完整的文档、配置选项和示例见 EXAMPLES.md中的多自定义域。 。 。 .

路线

SDK挂载路线如下:

1. /auth/login: 用户将重新定向启动认证交易的登录路径
2. /auth/logout: 必须添加到您的 Auth0 应用程序允许的日志 URL 的日志路径
3. /auth/callback: 必须在 Auth0 应用程序允许的回调 URL 中添加的回调路由
4. /auth/profile: 检查用户会话并返回其属性的路由
5. /auth/access-token: 检查用户会话并返回访问令牌的路由( 如果有刷新令牌, 将自动刷新)
6. /auth/backchannel-logout: 将接收到一个 logout_token 当配置的后通道日志启动器发生时
7. /auth/connect: 连接额外账户到当前用户会话的路由
8. /auth/mfa/authenticators: 列出当前用户注册的外交部认证器的路径
9. /auth/mfa/challenge: 为特定验证人启动外交部质疑的路线
10. /auth/mfa/verify: 核实外交部挑战反应和加快会议进度的路线
11. /auth/mfa/associate: 为当前用户注册一个新的 MFA 认证符的路径
12. /auth/passwordless/start: 发送 OTP 代码或魔法链接到用户的电子邮件或电话号码
13. /auth/passwordless/verify: 核查检察官办公室代码并创建会话
14. /auth/passwordless/otp/challenge:请检察官办公室提供数据库连接用户(电子邮件或电话)
15. /auth/passwordless/otp/token: 交换 a auth_session + OTP 值和创建会话
16. /auth/passkey/register: 为新用户注册获取 WebAuthn 证书创建挑战
17. /auth/passkey/challenge: 为已有用户登录获取 WebAuthn 证书断言挑战
18. /auth/passkey/get-token: 校验 WebAuthn 证书并创建会话

[注] 无密码路线( E)/auth/passwordless/start 财务报告和审定财务报表 /auth/passwordless/verify(b) 支助 电子邮件检察官办公室, (中文(简体) ), 短消息检察官办公室,以及 魔法链接 使用专用的无密码连接的流量。 对于魔法链接,用户点击电子邮件链接并被重定向到 /auth/callback ——不需要单独核查步骤. 魔法链接需要 allow_magiclink_verify_without_session 租户旗. 见 无密码认证 在 EXAMPLES.md 中,用于完整的设置和使用细节.

[注] 无密码的DBOTP路线(/auth/passwordless/otp/challenge 财务报告和审定财务报表 /auth/passwordless/otp/token与标准合作 数据库连接 配置为 email_otp 或者说 phone_otp ——非专用无密码连接. 使用 passwordless.challengeWithEmail(), (中文(简体) ), passwordless.challengeWithPhoneNumber(),以及 passwordless.loginWithOtp() 从 @auth0/nextjs-auth0/client。见 数据库连接上的无密码检察官办公室 在 EXAMPLES.md 中,用于完整的设置和使用细节.

[注] 密码路由执行 WebAuthn 仪式服务器侧. 使用 passkey 单吨从 @auth0/nextjs-auth0/client 完全一次性通知passkey.signup(), (中文(简体) ), passkey.login()),或者单独调用每条路线进行分步控制. 见 指南/passkeys.md中的密码认证 完整设置和使用细节.

[注]
这个 /auth/access-token 响应包括 token, (中文(简体) ), expires_at (纪元后秒), expires_in (TTL 秒),可选 scope选择 token_type如果您正在使用客户端助手 getAccessToken(),它默认只返回符号字符串;通过 { includeFullResponse: true } 以获得完整的应答有效载荷.

[TIP]
您可以在访问符过期前稍稍刷新 tokenRefreshBuffer (秒数) Auth0Client 配置 .

[大
这个 /auth/access-token 路由默认启用,但只有在客户端需要访问符时才有必要. 如果这不是你需要的东西,你可以通过设置来禁用这个终点 enableAccessTokenEndpoint 改为 false。 。 。 .

上游 IdP 的会话过期

对于企业连接,上游身份提供者可以限制用户的会话寿命. 当连接被配置以遵守时, Auth0 包含 a session_expiry 在 ID 符号 (通过 Post- Login 动作设置, 值必须是 Unix 秒) 中, SDK 在每次读取时执行此上限 。 一旦到达, getSession() 返回时 null, (中文(简体) ), useUser() 反映登录状态,以及 getAccessToken() 丢出一个 AccessTokenError 有代码 session_expired。如果上限在登录时已经存在,回调会立即拒绝。 假设一个会话在登录后总是存在的 Apps 应当添加无效检查并重定向回登录.

详情见 上游 IdP 的会话过期 (原始内容存档于2017-09-29). in EXAMPLES.md.

实验中心

[注] 实验中心通过SDKs的支持目前正在早期访问中. 要请求访问此功能, 请联系您的 Auth0 代表 .

实验中心 允许您测试您的登录流量。 通过通过强制执行特定变体 experiment_id 财务报告和审定财务报表 variation_id 每个日志, 作为查询参数 /auth/login 或经由 startInteractiveLogin数字 :

<a href="/auth/login?experiment_id=<EXPERIMENT_ID>&variation_id=<VARIATION_ID>">
  Log in
</a>

关于使用指导、分部定位和测试模式,见 向导/实验中心实验中心。 。 。 .

反馈

捐款

我们赞赏反馈和对这次再投资的贡献! 在开始前,请阅读以下内容:

• Auth0的一般贡献准则
• Auth0 行为守则准则
• 这个Repo的贡献指南

提出问题

请提供反馈或报告错误 提出我们的问题追踪器。 。 。 .

脆弱性报告

请不要在公共 GitHub 问题跟踪器上报告安全漏洞 。 这个 负责任的披露程序 详细说明披露安全问题的程序.

什么是奥特?

Auth0是一个易于执行,可适应的认证和授权平台. 学习更多退房 为什么是Auth0?

这个项目根据麻省理工学院的许可证获得许可。 见 自由主义 需要更多信息的文件.