NNext.js 中文网 GitHub

如何在 Next.js 中实现身份验证

了解如何在 Next.js 应用程序中实现身份验证。

理解身份验证对于保护应用程序的数据至关重要。本页将指导你使用哪些 React 和 Next.js 特性来实现身份验证。

在开始之前,将这个过程分解为三个概念会有所帮助:

  1. 身份验证:验证用户是否如其声称的身份。它要求用户使用其所拥有的凭据(例如用户名和密码)来证明身份。
  2. 会话管理:跨请求跟踪用户的身份验证状态。
  3. 授权:决定用户可以访问哪些路由和数据。

下图展示了使用 React 和 Next.js 特性的身份验证流程:

本页中的示例出于教学目的,演示了基本的用户名和密码身份验证。虽然你可以实现自定义的身份验证方案,但为了提高安全性和简化开发,我们建议使用身份验证库。这些库提供了身份验证、会话管理和授权的内置解决方案,以及社交登录、多因素身份验证和基于角色的访问控制等附加功能。你可以在身份验证库部分找到相关列表。

小知识: 启用 Cache Components 后,读取会话和缓存按用户划分的数据需遵循特定规则。请参阅使用 Cache Components 进行身份验证。

身份验证#

注册和登录功能#

你可以使用 <form> 元素,结合 React 的 Server Actions 和 useActionState 来获取用户凭据、验证表单字段,并调用你的身份验证提供方的 API 或数据库。

由于 Server Actions 始终在服务器上执行,它们为处理身份验证逻辑提供了安全的环境。

以下是实现注册/登录功能的步骤:

1. 获取用户凭据#

要获取用户凭据,请创建一个在提交时调用 Server Action 的表单。例如,一个接收用户姓名、邮箱和密码的注册表单:

app/ui/signup-form.tsx
import { signup } from '@/app/actions/auth'

export function SignupForm() {
  return (
    <form action={signup}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" name="name" placeholder="Name" />
      </div>
      <div>
        <label htmlFor="email">Email</label>
        <input id="email" name="email" type="email" placeholder="Email" />
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input id="password" name="password" type="password" />
      </div>
      <button type="submit">Sign Up</button>
    </form>
  )
}
app/ui/signup-form.js
import { signup } from '@/app/actions/auth'

export function SignupForm() {
  return (
    <form action={signup}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" name="name" placeholder="Name" />
      </div>
      <div>
        <label htmlFor="email">Email</label>
        <input id="email" name="email" type="email" placeholder="Email" />
      </div>
      <div>
        <label htmlFor="password">Password</label>
        <input id="password" name="password" type="password" />
      </div>
      <button type="submit">Sign Up</button>
    </form>
  )
}
app/actions/auth.ts
export async function signup(formData: FormData) {}
app/actions/auth.js
export async function signup(formData) {}

2. 在服务器上验证表单字段#

使用 Server Action 在服务器上验证表单字段。如果你的身份验证提供方不提供表单验证功能,你可以使用 Zod、Valibot 或 Yup 等模式验证库。

以 Zod 为例,你可以定义一个带有适当错误信息的表单模式:

app/lib/definitions.ts
import * as z from 'zod'

export const SignupFormSchema = z.object({
  name: z
    .string()
    .min(2, { error: 'Name must be at least 2 characters long.' })
    .trim(),
  email: z.email({ error: 'Please enter a valid email.' }).trim(),
  password: z
    .string()
    .min(8, { error: 'Be at least 8 characters long' })
    .regex(/[a-zA-Z]/, { error: 'Contain at least one letter.' })
    .regex(/[0-9]/, { error: 'Contain at least one number.' })
    .regex(/[^a-zA-Z0-9]/, {
      error: 'Contain at least one special character.',
    })
    .trim(),
})

export type FormState =
  | {
      errors?: {
        name?: string[]
        email?: string[]
        password?: string[]
      }
      message?: string
    }
  | undefined
app/lib/definitions.js
import * as z from 'zod'

export const SignupFormSchema = z.object({
  name: z
    .string()
    .min(2, { error: 'Name must be at least 2 characters long.' })
    .trim(),
  email: z.email({ error: 'Please enter a valid email.' }).trim(),
  password: z
    .string()
    .min(8, { error: 'Be at least 8 characters long' })
    .regex(/[a-zA-Z]/, { error: 'Contain at least one letter.' })
    .regex(/[0-9]/, { error: 'Contain at least one number.' })
    .regex(/[^a-zA-Z0-9]/, {
      error: 'Contain at least one special character.',
    })
    .trim(),
})

为避免对身份验证提供方的 API 或数据库进行不必要的调用,如果有任何表单字段与定义的模式不匹配,你可以在 Server Action 中提前 return。

app/actions/auth.ts
import { SignupFormSchema, FormState } from '@/app/lib/definitions'

export async function signup(state: FormState, formData: FormData) {
  // 验证表单字段
  const validatedFields = SignupFormSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  })

  // 如果有任何表单字段无效,则提前返回
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }

  // 调用提供方或数据库来创建用户...
}
app/actions/auth.js
import { SignupFormSchema } from '@/app/lib/definitions'

export async function signup(state, formData) {
  // 验证表单字段
  const validatedFields = SignupFormSchema.safeParse({
    name: formData.get('name'),
    email: formData.get('email'),
    password: formData.get('password'),
  })

  // 如果有任何表单字段无效,则提前返回
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }

  // 调用提供方或数据库来创建用户...
}

回到你的 <SignupForm />,你可以使用 React 的 useActionState hook 在表单提交时显示验证错误:

app/ui/signup-form.tsx
'use client'

import { signup } from '@/app/actions/auth'
import { useActionState } from 'react'

export default function SignupForm() {
  const [state, action, pending] = useActionState(signup, undefined)

  return (
    <form action={action}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" name="name" placeholder="Name" />
      </div>
      {state?.errors?.name && <p>{state.errors.name}</p>}

      <div>
        <label htmlFor="email">Email</label>
        <input id="email" name="email" placeholder="Email" />
      </div>
      {state?.errors?.email && <p>{state.errors.email}</p>}

      <div>
        <label htmlFor="password">Password</label>
        <input id="password" name="password" type="password" />
      </div>
      {state?.errors?.password && (
        <div>
          <p>Password must:</p>
          <ul>
            {state.errors.password.map((error) => (
              <li key={error}>- {error}</li>
            ))}
          </ul>
        </div>
      )}
      <button disabled={pending} type="submit">
        Sign Up
      </button>
    </form>
  )
}
app/ui/signup-form.js
'use client'

import { signup } from '@/app/actions/auth'
import { useActionState } from 'react'

export default function SignupForm() {
  const [state, action, pending] = useActionState(signup, undefined)

  return (
    <form action={action}>
      <div>
        <label htmlFor="name">Name</label>
        <input id="name" name="name" placeholder="Name" />
      </div>
      {state?.errors?.name && <p>{state.errors.name}</p>}

      <div>
        <label htmlFor="email">Email</label>
        <input id="email" name="email" placeholder="Email" />
      </div>
      {state?.errors?.email && <p>{state.errors.email}</p>}

      <div>
        <label htmlFor="password">Password</label>
        <input id="password" name="password" type="password" />
      </div>
      {state?.errors?.password && (
        <div>
          <p>Password must:</p>
          <ul>
            {state.errors.password.map((error) => (
              <li key={error}>- {error}</li>
            ))}
          </ul>
        </div>
      )}
      <button disabled={pending} type="submit">
        Sign Up
      </button>
    </form>
  )
}

小知识:

  • 在 React 19 中,useFormStatus 在返回的对象上包含额外的键,如 data、method 和 action。如果你使用的不是 React 19,则只有 pending 键可用。
  • 在修改数据之前,你应始终确保用户也有权执行该操作。请参阅身份验证和授权。

3. 创建用户或检查用户凭据#

验证表单字段后,你可以通过调用身份验证提供方的 API 或数据库来创建新用户账户,或检查用户是否存在。

沿用前面的示例:

app/actions/auth.tsx
export async function signup(state: FormState, formData: FormData) {
  // 1. 验证表单字段
  // ...

  // 2. 准备要插入数据库的数据
  const { name, email, password } = validatedFields.data
  // 例如,在存储之前对用户密码进行哈希处理
  const hashedPassword = await bcrypt.hash(password, 10)

  // 3. 将用户插入数据库或调用身份验证库的 API
  const data = await db
    .insert(users)
    .values({
      name,
      email,
      password: hashedPassword,
    })
    .returning({ id: users.id })

  const user = data[0]

  if (!user) {
    return {
      message: 'An error occurred while creating your account.',
    }
  }

  // TODO:
  // 4. 创建用户会话
  // 5. 重定向用户
}
app/actions/auth.js
export async function signup(state, formData) {
  // 1. 验证表单字段
  // ...

  // 2. 准备要插入数据库的数据
  const { name, email, password } = validatedFields.data
  // 例如,在存储之前对用户密码进行哈希处理
  const hashedPassword = await bcrypt.hash(password, 10)

  // 3. 将用户插入数据库或调用库的 API
  const data = await db
    .insert(users)
    .values({
      name,
      email,
      password: hashedPassword,
    })
    .returning({ id: users.id })

  const user = data[0]

  if (!user) {
    return {
      message: 'An error occurred while creating your account.',
    }
  }

  // TODO:
  // 4. 创建用户会话
  // 5. 重定向用户
}

成功创建用户账户或验证用户凭据后,你可以创建会话来管理用户的身份验证状态。根据你的会话管理策略,会话可以存储在 cookie、数据库或两者中。继续阅读会话管理部分了解更多信息。

提示:

  • 上面的示例较为冗长,因为它出于教学目的将身份验证步骤进行了拆分。这也说明,实现自己的安全方案很快就会变得复杂。可以考虑使用身份验证库来简化流程。
  • 为了改善用户体验,你可能希望在注册流程的更早阶段检查邮箱或用户名是否重复。例如,在用户输入用户名时或输入字段失去焦点时。这有助于避免不必要的表单提交,并向用户提供即时反馈。你可以使用 use-debounce 等库对请求进行防抖,以控制这些检查的频率。

以下是实现注册和/或登录表单的步骤:

  1. 用户通过表单提交凭据。
  2. 表单发送一个由 API 路由处理的请求。
  3. 验证成功后,流程完成,表示用户已成功通过身份验证。
  4. 如果验证失败,则显示错误消息。

以一个用户可以输入凭据的登录表单为例:

pages/login.tsx
import type { SubmitEvent } from 'react'
import { useRouter } from 'next/router'

export default function LoginPage() {
  const router = useRouter()

  async function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
    event.preventDefault()

    const formData = new FormData(event.currentTarget)
    const email = formData.get('email')
    const password = formData.get('password')

    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    })

    if (response.ok) {
      router.push('/profile')
    } else {
      // 处理错误
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" placeholder="Email" required />
      <input type="password" name="password" placeholder="Password" required />
      <button type="submit">Login</button>
    </form>
  )
}
pages/login.jsx
import { useRouter } from 'next/router'

export default function LoginPage() {
  const router = useRouter()

  async function handleSubmit(event) {
    event.preventDefault()

    const formData = new FormData(event.currentTarget)
    const email = formData.get('email')
    const password = formData.get('password')

    const response = await fetch('/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password }),
    })

    if (response.ok) {
      router.push('/profile')
    } else {
      // 处理错误
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" placeholder="Email" required />
      <input type="password" name="password" placeholder="Password" required />
      <button type="submit">Login</button>
    </form>
  )
}

上面的表单有两个输入字段,用于获取用户的邮箱和密码。提交时,它会触发一个向 API 路由(/api/auth/login)发送 POST 请求的函数。

然后你可以在 API 路由中调用身份验证提供方的 API 来处理身份验证:

pages/api/auth/login.ts
import type { NextApiRequest, NextApiResponse } from 'next'
import { signIn } from '@/auth'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    const { email, password } = req.body
    await signIn('credentials', { email, password })

    res.status(200).json({ success: true })
  } catch (error) {
    if (error.type === 'CredentialsSignin') {
      res.status(401).json({ error: 'Invalid credentials.' })
    } else {
      res.status(500).json({ error: 'Something went wrong.' })
    }
  }
}
pages/api/auth/login.js
import { signIn } from '@/auth'

export default async function handler(req, res) {
  try {
    const { email, password } = req.body
    await signIn('credentials', { email, password })

    res.status(200).json({ success: true })
  } catch (error) {
    if (error.type === 'CredentialsSignin') {
      res.status(401).json({ error: 'Invalid credentials.' })
    } else {
      res.status(500).json({ error: 'Something went wrong.' })
    }
  }
}

会话管理#

会话管理确保用户的已验证状态在多个请求之间得以保持。它包括创建、存储、刷新和删除会话或令牌。

会话有两种类型:

  1. 无状态:会话数据(或令牌)存储在浏览器的 cookie 中。cookie 会随每个请求一起发送,从而可以在服务器上验证会话。这种方法更简单,但如果实现不当,安全性可能较低。
  2. 数据库:会话数据存储在数据库中,用户的浏览器只接收加密后的会话 ID。这种方法更安全,但可能比较复杂,且会占用更多服务器资源。

小知识: 虽然你可以任选一种方法,或两者结合使用,但我们建议使用会话管理库,例如 iron-session 或 Jose。

无状态会话#

要创建和管理无状态会话,需要遵循以下几个步骤:

  1. 生成一个密钥,用于签署会话,并将其存储为环境变量。
  2. 编写逻辑,使用会话管理库对会话数据进行加密/解密。
  3. 使用 Next.js 的 cookies API 管理 cookie。

除上述步骤外,还可以考虑增加以下功能:当用户返回应用时更新(或刷新)会话,以及当用户退出登录时删除会话。

小知识: 请查看你的身份验证库是否包含会话管理功能。

1. 生成密钥#

有多种方法可以生成用于签署会话的密钥。例如,你可以在终端中使用 openssl 命令:

terminal
openssl rand -base64 32

此命令会生成一个 32 个字符的随机字符串,你可以将其用作密钥,并存储在你的环境变量文件中:

.env
SESSION_SECRET=your_secret_key

然后你可以在会话管理逻辑中引用这个密钥:

app/lib/session.js
const secretKey = process.env.SESSION_SECRET

2. 加密和解密会话#

接下来,你可以使用你偏好的会话管理库来加密和解密会话。沿用前面的示例,我们将使用 Jose 和 React 的 server-only 包,以确保你的会话管理逻辑只在服务器上执行。

app/lib/session.ts
import 'server-only'
import { SignJWT, jwtVerify } from 'jose'
import { SessionPayload } from '@/app/lib/definitions'

const secretKey = process.env.SESSION_SECRET
const encodedKey = new TextEncoder().encode(secretKey)

export async function encrypt(payload: SessionPayload) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(encodedKey)
}

export async function decrypt(session: string | undefined = '') {
  try {
    const { payload } = await jwtVerify(session, encodedKey, {
      algorithms: ['HS256'],
    })
    return payload
  } catch (error) {
    console.log('Failed to verify session')
  }
}
app/lib/session.js
import 'server-only'
import { SignJWT, jwtVerify } from 'jose'

const secretKey = process.env.SESSION_SECRET
const encodedKey = new TextEncoder().encode(secretKey)

export async function encrypt(payload) {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('7d')
    .sign(encodedKey)
}

export async function decrypt(session) {
  try {
    const { payload } = await jwtVerify(session, encodedKey, {
      algorithms: ['HS256'],
    })
    return payload
  } catch (error) {
    console.log('Failed to verify session')
  }
}

提示:

  • payload 应包含后续请求中会用到的最少量的唯一用户数据,例如用户 ID、角色等。它不应包含个人身份信息(如电话号码、邮箱地址、信用卡信息等),也不应包含密码等敏感数据。

要将会话存储在 cookie 中,请使用 Next.js 的 cookies API。cookie 应在服务器上设置,并包含以下推荐选项:

  • HttpOnly:阻止客户端 JavaScript 访问该 cookie。
  • Secure:使用 https 发送 cookie。
  • SameSite:指定 cookie 是否可以随跨站请求一起发送。
  • Max-Age 或 Expires:在一段时间后删除 cookie。
  • Path:定义 cookie 的 URL 路径。

有关每个选项的更多信息,请参阅 MDN。

app/lib/session.ts
import 'server-only'
import { cookies } from 'next/headers'

export async function createSession(userId: string) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  const session = await encrypt({ userId, expiresAt })
  const cookieStore = await cookies()

  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}
app/lib/session.js
import 'server-only'
import { cookies } from 'next/headers'

export async function createSession(userId) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  const session = await encrypt({ userId, expiresAt })
  const cookieStore = await cookies()

  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}

回到你的 Server Action,你可以调用 createSession() 函数,并使用 redirect() API 将用户重定向到合适的页面:

app/actions/auth.ts
import { createSession } from '@/app/lib/session'

export async function signup(state: FormState, formData: FormData) {
  // 之前的步骤:
  // 1. 验证表单字段
  // 2. 准备要插入数据库的数据
  // 3. 将用户插入数据库或调用库的 API

  // 当前的步骤:
  // 4. 创建用户会话
  await createSession(user.id)
  // 5. 重定向用户
  redirect('/profile')
}
app/actions/auth.js
import { createSession } from '@/app/lib/session'

export async function signup(state, formData) {
  // 之前的步骤:
  // 1. 验证表单字段
  // 2. 准备要插入数据库的数据
  // 3. 将用户插入数据库或调用库的 API

  // 当前的步骤:
  // 4. 创建用户会话
  await createSession(user.id)
  // 5. 重定向用户
  redirect('/profile')
}

提示:

  • cookie 应在服务器上设置,以防止客户端篡改。
  • 🎥 观看:了解有关使用 Next.js 实现无状态会话和身份验证的更多信息 → YouTube(11 分钟)。

更新(或刷新)会话#

你还可以延长会话的过期时间。这有助于在用户再次访问应用后保持其登录状态。例如:

app/lib/session.ts
import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export async function updateSession() {
  const session = (await cookies()).get('session')?.value
  const payload = await decrypt(session)

  if (!session || !payload) {
    return null
  }

  const expires = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expires,
    sameSite: 'lax',
    path: '/',
  })
}
app/lib/session.js
import 'server-only'
import { cookies } from 'next/headers'
import { decrypt } from '@/app/lib/session'

export async function updateSession() {
  const cookieStore = await cookies()
  const session = cookieStore.get('session')?.value
  const payload = await decrypt(session)

  if (!session || !payload) {
    return null
  }

  const expires = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expires,
    sameSite: 'lax',
    path: '/',
  })
}

提示: 请查看你的身份验证库是否支持刷新令牌,刷新令牌可用于延长用户的会话。

删除会话#

要删除会话,你可以删除对应的 cookie:

app/lib/session.ts
import 'server-only'
import { cookies } from 'next/headers'

export async function deleteSession() {
  const cookieStore = await cookies()
  cookieStore.delete('session')
}
app/lib/session.js
import 'server-only'
import { cookies } from 'next/headers'

export async function deleteSession() {
  const cookieStore = await cookies()
  cookieStore.delete('session')
}

然后你可以在应用中复用 deleteSession() 函数,例如在退出登录时:

app/actions/auth.ts
import { cookies } from 'next/headers'
import { deleteSession } from '@/app/lib/session'

export async function logout() {
  await deleteSession()
  redirect('/login')
}
app/actions/auth.js
import { cookies } from 'next/headers'
import { deleteSession } from '@/app/lib/session'

export async function logout() {
  await deleteSession()
  redirect('/login')
}

你可以使用 API Routes 在服务器上将会话设置为 cookie:

pages/api/login.ts
import { serialize } from 'cookie'
import type { NextApiRequest, NextApiResponse } from 'next'
import { encrypt } from '@/app/lib/session'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  const sessionData = req.body
  const encryptedSessionData = encrypt(sessionData)

  const cookie = serialize('session', encryptedSessionData, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 60 * 60 * 24 * 7, // 一周
    path: '/',
  })
  res.setHeader('Set-Cookie', cookie)
  res.status(200).json({ message: 'Successfully set cookie!' })
}
pages/api/login.js
import { serialize } from 'cookie'
import { encrypt } from '@/app/lib/session'

export default function handler(req, res) {
  const sessionData = req.body
  const encryptedSessionData = encrypt(sessionData)

  const cookie = serialize('session', encryptedSessionData, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    maxAge: 60 * 60 * 24 * 7, // 一周
    path: '/',
  })
  res.setHeader('Set-Cookie', cookie)
  res.status(200).json({ message: 'Successfully set cookie!' })
}

数据库会话#

要创建和管理数据库会话,你需要遵循以下步骤:

  1. 在数据库中创建一个表来存储会话和数据(或查看你的身份验证库是否已处理此功能)。
  2. 实现插入、更新和删除会话的功能
  3. 在将会话 ID 存储到用户浏览器之前对其进行加密,并确保数据库和 cookie 保持同步(这是可选项,但建议在 Proxy 中进行乐观身份验证检查时使用)。

例如:

app/lib/session.ts
import { cookies } from 'next/headers'
import { db } from '@/app/lib/db'
import { encrypt } from '@/app/lib/session'

export async function createSession(id: number) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  // 1. 在数据库中创建会话
  const data = await db
    .insert(sessions)
    .values({
      userId: id,
      expiresAt,
    })
    // 返回会话 ID
    .returning({ id: sessions.id })

  const sessionId = data[0].id

  // 2. 加密会话 ID
  const session = await encrypt({ sessionId, expiresAt })

  // 3. 将会话存储在 cookie 中,用于乐观身份验证检查
  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}
app/lib/session.js
import { cookies } from 'next/headers'
import { db } from '@/app/lib/db'
import { encrypt } from '@/app/lib/session'

export async function createSession(id) {
  const expiresAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)

  // 1. 在数据库中创建会话
  const data = await db
    .insert(sessions)
    .values({
      userId: id,
      expiresAt,
    })
    // 返回会话 ID
    .returning({ id: sessions.id })

  const sessionId = data[0].id

  // 2. 加密会话 ID
  const session = await encrypt({ sessionId, expiresAt })

  // 3. 将会话存储在 cookie 中,用于乐观身份验证检查
  const cookieStore = await cookies()
  cookieStore.set('session', session, {
    httpOnly: true,
    secure: true,
    expires: expiresAt,
    sameSite: 'lax',
    path: '/',
  })
}

提示:

  • 为了更快地访问,你可以考虑在会话的生命周期内添加服务器端缓存。你也可以将会话数据保留在主数据库中,并合并数据请求以减少查询次数。
  • 对于更高级的用例,你可以选择使用数据库会话,例如记录用户上次登录的时间、活跃设备数量,或让用户能够退出所有设备。

实现会话管理后,你需要添加授权逻辑,以控制用户在应用中可以访问和执行的操作。继续阅读授权部分了解更多信息。

在服务器上创建会话:

pages/api/create-session.ts
import db from '../../lib/db'
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    const user = req.body
    const sessionId = generateSessionId()
    await db.insertSession({
      sessionId,
      userId: user.id,
      createdAt: new Date(),
    })

    res.status(200).json({ sessionId })
  } catch (error) {
    res.status(500).json({ error: 'Internal Server Error' })
  }
}
pages/api/create-session.js
import db from '../../lib/db'

export default async function handler(req, res) {
  try {
    const user = req.body
    const sessionId = generateSessionId()
    await db.insertSession({
      sessionId,
      userId: user.id,
      createdAt: new Date(),
    })

    res.status(200).json({ sessionId })
  } catch (error) {
    res.status(500).json({ error: 'Internal Server Error' })
  }
}

授权#

一旦用户通过身份验证并创建了会话,你就可以实现授权,以控制用户在应用中可以访问和执行的操作。

授权检查主要有两种类型:

  1. 乐观检查:使用存储在 cookie 中的会话数据,检查用户是否有权访问路由或执行操作。这类检查适用于快速操作,例如显示/隐藏 UI 元素,或根据权限或角色重定向用户。
  2. 安全检查:使用存储在数据库中的会话数据,检查用户是否有权访问路由或执行操作。这类检查更安全,用于需要访问敏感数据或敏感操作的情景。

对于这两种情况,我们建议:

使用 Proxy 进行乐观检查(可选)#

在某些情况下,你可能希望使用 Proxy 并根据权限重定向用户:

  • 执行乐观检查。由于 Proxy 会在每个路由上运行,因此它是集中管理重定向逻辑并预先过滤未授权用户的好方法。
  • 保护在用户之间共享数据的静态路由(例如付费墙背后的内容)。

不过,由于 Proxy 会在每个路由上运行,包括预取的路由,因此务必只从 cookie 中读取会话(乐观检查),并避免进行数据库检查,以防出现性能问题。

例如:

proxy.ts
import { NextRequest, NextResponse } from 'next/server'
import { decrypt } from '@/app/lib/session'
import { cookies } from 'next/headers'

// 1. 指定受保护和公开的路由
const protectedRoutes = ['/dashboard']
const publicRoutes = ['/login', '/signup', '/']

export default async function proxy(req: NextRequest) {
  // 2. 检查当前路由是受保护还是公开的
  const path = req.nextUrl.pathname
  const isProtectedRoute = protectedRoutes.includes(path)
  const isPublicRoute = publicRoutes.includes(path)

  // 3. 从 cookie 中解密会话
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  // 4. 如果用户未通过身份验证,则重定向到 /login
  if (isProtectedRoute && !session?.userId) {
    return NextResponse.redirect(new URL('/login', req.nextUrl))
  }

  // 5. 如果用户已通过身份验证,则重定向到 /dashboard
  if (
    isPublicRoute &&
    session?.userId &&
    !req.nextUrl.pathname.startsWith('/dashboard')
  ) {
    return NextResponse.redirect(new URL('/dashboard', req.nextUrl))
  }

  return NextResponse.next()
}

// Proxy 不应运行的路由
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
}
proxy.js
import { NextResponse } from 'next/server'
import { decrypt } from '@/app/lib/session'
import { cookies } from 'next/headers'

// 1. 指定受保护和公开的路由
const protectedRoutes = ['/dashboard']
const publicRoutes = ['/login', '/signup', '/']

export default async function proxy(req) {
  // 2. 检查当前路由是受保护还是公开的
  const path = req.nextUrl.pathname
  const isProtectedRoute = protectedRoutes.includes(path)
  const isPublicRoute = publicRoutes.includes(path)

  // 3. 从 cookie 中解密会话
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  // 5. 如果用户未通过身份验证,则重定向到 /login
  if (isProtectedRoute && !session?.userId) {
    return NextResponse.redirect(new URL('/login', req.nextUrl))
  }

  // 6. 如果用户已通过身份验证,则重定向到 /dashboard
  if (
    isPublicRoute &&
    session?.userId &&
    !req.nextUrl.pathname.startsWith('/dashboard')
  ) {
    return NextResponse.redirect(new URL('/dashboard', req.nextUrl))
  }

  return NextResponse.next()
}

// Proxy 不应运行的路由
export const config = {
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
}

虽然 Proxy 对初步检查很有用,但它不应成为保护数据的唯一防线。大多数安全检查应尽可能靠近数据源执行,有关更多信息,请参阅数据访问层。

提示:

  • 在 Proxy 中,你也可以使用 req.cookies.get('session')?.value 来读取 cookie。
  • Proxy 使用 Node.js 运行时,请检查你的身份验证库和会话管理库是否兼容。
  • 你可以使用 Proxy 中的 matcher 属性来指定 Proxy 应在哪些路由上运行。不过,对于身份验证,建议 Proxy 在所有路由上运行。

创建数据访问层(DAL)#

我们建议创建一个 DAL 来集中管理数据请求和授权逻辑。

DAL 应包含一个在用户与你的应用交互时验证其会话的函数。至少,该函数应检查会话是否有效,然后重定向或返回进一步请求所需的用户信息。

例如,为你的 DAL 创建一个单独的文件,其中包含 verifySession() 函数。然后使用 React 的 cache API 在 React 渲染过程中对函数的返回值进行记忆化:

app/lib/dal.ts
import 'server-only'

import { cache } from 'react'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
import { decrypt } from '@/app/lib/session'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session?.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId }
})
app/lib/dal.js
import 'server-only'

import { cache } from 'react'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
import { decrypt } from '@/app/lib/session'

export const verifySession = cache(async () => {
  const cookie = (await cookies()).get('session')?.value
  const session = await decrypt(cookie)

  if (!session.userId) {
    redirect('/login')
  }

  return { isAuth: true, userId: session.userId }
})

然后你可以在数据请求、Server Actions 和 Route Handlers 中调用 verifySession() 函数:

小知识:React 的 cache 会在一次 React 渲染过程中进行去重。Server Actions 和 Route Handlers 不属于渲染过程,因此该包装器不起作用,每次调用都会执行该函数。

app/lib/dal.ts
export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  try {
    const data = await db.query.users.findMany({
      where: eq(users.id, session.userId),
      // 显式返回你需要的列,而不是整个用户对象
      columns: {
        id: true,
        name: true,
        email: true,
      },
    })

    const user = data[0]

    return user
  } catch (error) {
    console.log('Failed to fetch user')
    return null
  }
})
app/lib/dal.js
export const getUser = cache(async () => {
  const session = await verifySession()
  if (!session) return null

  try {
    const data = await db.query.users.findMany({
      where: eq(users.id, session.userId),
      // 显式返回你需要的列,而不是整个用户对象
      columns: {
        id: true,
        name: true,
        email: true,
      },
    })

    const user = data[0]

    return user
  } catch (error) {
    console.log('Failed to fetch user')
    return null
  }
})

提示:

  • DAL 可用于保护在请求时获取的数据。不过,对于在用户之间共享数据的静态路由,数据会在构建时而非请求时获取。请使用 Proxy 来保护静态路由。
  • 对于安全检查,你可以通过将会话 ID 与数据库进行比对来检查会话是否有效。使用 React 的 cache 函数,可以避免在一次渲染过程中对数据库进行不必要的重复请求。
  • 你可能希望将相关的数据请求整合到一个 JavaScript 类中,该类在任何方法执行前都会先运行 verifySession()。

使用数据传输对象(DTO)#

检索数据时,建议只返回应用中会用到的必要数据,而不是整个对象。例如,如果你要获取用户数据,可以只返回用户的 ID 和姓名,而不是可能包含密码、电话号码等信息的整个用户对象。

不过,如果你无法控制返回的数据结构,或者在团队开发中希望避免将整个对象传递给客户端,你可以使用一些策略,例如指定哪些字段可以安全地暴露给客户端。

app/lib/dto.ts
import 'server-only'
import { getUser } from '@/app/lib/dal'

function canSeeUsername(viewer: User) {
  return true
}

function canSeePhoneNumber(viewer: User, team: string) {
  return viewer.isAdmin || team === viewer.team
}

export async function getProfileDTO(slug: string) {
  const data = await db.query.users.findMany({
    where: eq(users.slug, slug),
    // 在此返回特定的列
  })
  const user = data[0]

  const currentUser = await getUser(user.id)

  // 或者在此只返回与该查询相关的字段
  return {
    username: canSeeUsername(currentUser) ? user.username : null,
    phonenumber: canSeePhoneNumber(currentUser, user.team)
      ? user.phonenumber
      : null,
  }
}
app/lib/dto.js
import 'server-only'
import { getUser } from '@/app/lib/dal'

function canSeeUsername(viewer) {
  return true
}

function canSeePhoneNumber(viewer, team) {
  return viewer.isAdmin || team === viewer.team
}

export async function getProfileDTO(slug) {
  const data = await db.query.users.findMany({
    where: eq(users.slug, slug),
    // 在此返回特定的列
  })
  const user = data[0]

  const currentUser = await getUser(user.id)

  // 或者在此只返回与该查询相关的字段
  return {
    username: canSeeUsername(currentUser) ? user.username : null,
    phonenumber: canSeePhoneNumber(currentUser, user.team)
      ? user.phonenumber
      : null,
  }
}

通过将数据请求和授权逻辑集中在 DAL 中并使用 DTO,你可以确保所有数据请求都安全且一致,从而在应用规模扩大时更易于维护、审计和调试。

小知识:

  • 定义 DTO 有多种不同的方式,从使用 toJSON(),到像上面示例这样的单个函数,或是 JS 类。由于这些是 JavaScript 模式,而非 React 或 Next.js 的特性,我们建议你做一些研究,以找到最适合你的应用的模式。
  • 在我们的《Next.js 中的安全性》文章中了解更多安全最佳实践。

Server Components#

在 Server Components 中进行身份验证检查有助于实现基于角色的访问控制。例如,根据用户角色有条件地渲染组件:

app/dashboard/page.tsx
import { verifySession } from '@/app/lib/dal'

export default async function Dashboard() {
  const session = await verifySession()
  const userRole = session?.role // 假设 'role' 是会话对象的一部分

  if (userRole === 'admin') {
    return <AdminDashboard />
  } else if (userRole === 'user') {
    return <UserDashboard />
  } else {
    redirect('/login')
  }
}
app/dashboard/page.jsx
import { verifySession } from '@/app/lib/dal'

export default async function Dashboard() {
  const session = await verifySession()
  const userRole = session?.role // 假设 'role' 是会话对象的一部分

  if (userRole === 'admin') {
    return <AdminDashboard />
  } else if (userRole === 'user') {
    return <UserDashboard />
  } else {
    redirect('/login')
  }
}

在示例中,我们使用 DAL 中的 verifySession() 函数来检查 'admin'、'user' 和未授权角色。这种模式确保每个用户只与其角色相符的组件进行交互。

Layout 与身份验证检查#

由于部分渲染,在 Layout 中执行检查时要谨慎,因为 Layout 不会在导航时重新渲染,这意味着用户会话不会在每次路由变化时都得到检查。

Layout 也无法控制路由的其余部分是否渲染。路由段和并行路由插槽由路由器渲染,因此隐藏或替换它们的 Layout 并不能阻止它们运行,也无法阻止它们出现在 RSC Payload 中。

相反,你应该在靠近数据源或将被条件渲染的组件的位置执行检查。

例如,假设有一个共享 Layout,它获取用户数据并在导航栏中显示用户头像。你不应该在 Layout 中执行身份验证检查,而应该在 Layout 中获取用户数据(getUser()),并在你的 DAL 中执行身份验证检查。

这可以保证,无论应用中何处调用 getUser(),都会执行身份验证检查,并防止开发人员忘记检查用户是否有权访问数据。

身份验证与流式渲染#

会话和用户数据通常出现在跨路由重复的 shell UI(页头、导航栏)中。在 Layout 中对 cookies()、headers() 或 DAL 进行顶层 await,会延迟该段第一个流式分块的发送,并使 {children} 等待该工作完成。

如果只有 shell 的一部分需要会话数据(例如用户菜单),请将 await 移入嵌套的 Server Component,并用 <Suspense> 包裹它,以便页面的其余部分先进行流式传输。有关这种模式,请参阅下推动态访问。

Client Components 无法导入 DAL。请在父级 Server Component 中运行 verifySession()、getUser() 或类似函数,然后通过 props 或 context provider 将数据传递给客户端子组件。有关这种模式,请参阅在 Context Provider 中使用 React 的 use,并使用 React 的 taintUniqueValue API 来防止敏感的会话字段传到客户端。

页面组件中的身份验证检查#

例如,在仪表盘页面中,你可以验证用户会话并获取用户数据:

app/dashboard/page.tsx
import { verifySession } from '@/app/lib/dal'

export default async function DashboardPage() {
  const session = await verifySession()

  // 从你的数据库或数据源中获取特定于用户的数据
  const user = await getUserData(session.userId)

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      
    </div>
  )
}
app/dashboard/page.jsx
import { verifySession } from '@/app/lib/dal'

export default async function DashboardPage() {
  const session = await verifySession()

  // 从你的数据库或数据源中获取特定于用户的数据
  const user = await getUserData(session.userId)

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      
    </div>
  )
}

叶子组件中的身份验证检查#

你还可以在叶子组件中执行身份验证检查,根据用户权限有条件地渲染 UI 元素。例如,一个显示仅管理员可用操作的组件:

app/ui/admin-actions.tsx
import { verifySession } from '@/app/lib/dal'

export default async function AdminActions() {
  const session = await verifySession()
  const userRole = session?.role

  if (userRole !== 'admin') {
    return null
  }

  return (
    <div>
      <button>Delete User</button>
      <button>Edit Settings</button>
    </div>
  )
}
app/ui/admin-actions.jsx
import { verifySession } from '@/app/lib/dal'

export default async function AdminActions() {
  const session = await verifySession()
  const userRole = session?.role

  if (userRole !== 'admin') {
    return null
  }

  return (
    <div>
      <button>Delete User</button>
      <button>Edit Settings</button>
    </div>
  )
}

这种模式允许你根据用户权限显示或隐藏 UI 元素,同时确保身份验证检查在每个组件的渲染时执行。

小知识:

  • SPA 中一种常见模式是,当用户未获授权时在 Layout 或顶层组件中 return null。不推荐使用这种模式,因为 Next.js 应用有多个入口点,这无法阻止嵌套路由段和 Server Actions 被访问。
  • 请确保从这些组件调用的任何 Server Actions 也会执行自身的授权检查,因为仅靠客户端 UI 限制不足以保证安全。

Server Actions#

应将 Server Actions 与面向公众的 API 端点一视同仁地考虑安全性,并验证用户是否有权执行数据变更。

在下面的示例中,我们会在允许操作继续执行之前检查用户的角色:

app/lib/actions.ts
'use server'
import { verifySession } from '@/app/lib/dal'

export async function serverAction(formData: FormData) {
  const session = await verifySession()
  const userRole = session?.role

  // 如果用户无权执行该操作,则提前返回
  if (userRole !== 'admin') {
    return null
  }

  // 对已授权用户继续执行该操作
}
app/lib/actions.js
'use server'
import { verifySession } from '@/app/lib/dal'

export async function serverAction() {
  const session = await verifySession()
  const userRole = session?.role

  // 如果用户无权执行该操作,则提前返回
  if (userRole !== 'admin') {
    return null
  }

  // 对已授权用户继续执行该操作
}

Route Handlers#

应将 Route Handlers 与面向公众的 API 端点一视同仁地考虑安全性,并验证用户是否有权访问该 Route Handler。

例如:

app/api/route.ts
import { verifySession } from '@/app/lib/dal'

export async function GET() {
  // 用户身份验证和角色验证
  const session = await verifySession()

  // 检查用户是否已通过身份验证
  if (!session) {
    // 用户未通过身份验证
    return new Response(null, { status: 401 })
  }

  // 检查用户是否具有 'admin' 角色
  if (session?.role !== 'admin') {
    // 用户已通过身份验证,但没有相应权限
    return new Response(null, { status: 403 })
  }

  // 对已授权用户继续执行
}
app/api/route.js
import { verifySession } from '@/app/lib/dal'

export async function GET() {
  // 用户身份验证和角色验证
  const session = await verifySession()

  // 检查用户是否已通过身份验证
  if (!session) {
    // 用户未通过身份验证
    return new Response(null, { status: 401 })
  }

  // 检查用户是否具有 'admin' 角色
  if (session?.role !== 'admin') {
    // 用户已通过身份验证,但没有相应权限
    return new Response(null, { status: 403 })
  }

  // 对已授权用户继续执行
}

上面的示例演示了一个具有两级安全检查的 Route Handler。它首先检查是否存在有效会话,然后验证已登录的用户是否为 'admin'。

创建数据访问层(DAL)#

保护 API Routes#

Next.js 中的 API Routes 对于处理服务器端逻辑和数据管理至关重要。保护这些路由以确保只有授权用户才能访问特定功能十分重要。这通常涉及验证用户的身份验证状态及其基于角色的权限。

以下是保护 API Route 的示例:

pages/api/route.ts
import { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const session = await getSession(req)

  // 检查用户是否已通过身份验证
  if (!session) {
    res.status(401).json({
      error: 'User is not authenticated',
    })
    return
  }

  // 检查用户是否具有 'admin' 角色
  if (session.user.role !== 'admin') {
    res.status(401).json({
      error: 'Unauthorized access: User does not have admin privileges.',
    })
    return
  }

  // 对已授权用户继续执行该路由
  // ... API Route 的实现
}
pages/api/route.js
export default async function handler(req, res) {
  const session = await getSession(req)

  // 检查用户是否已通过身份验证
  if (!session) {
    res.status(401).json({
      error: 'User is not authenticated',
    })
    return
  }

  // 检查用户是否具有 'admin' 角色
  if (session.user.role !== 'admin') {
    res.status(401).json({
      error: 'Unauthorized access: User does not have admin privileges.',
    })
    return
  }

  // 对已授权用户继续执行该路由
  // ... API Route 的实现
}

此示例演示了一个对身份验证和授权进行两级安全检查的 API Route。它首先检查是否存在有效会话,然后验证已登录的用户是否为 'admin'。这种方法确保只有经过身份验证和授权的用户才能安全访问,从而为请求处理维持强大的安全性。

资源#

现在你已经了解了 Next.js 中的身份验证,以下是一些与 Next.js 兼容的库和资源,可帮助你实现安全的身份验证和会话管理:

身份验证库#

会话管理库#

延伸阅读#

要继续学习身份验证和安全方面的知识,请查看以下资源:

Next.js 中文网