React / 系统课时

设计接口鉴权

设计接口鉴权

接口鉴权的目标不是“读到一个 token 就放行”,而是把凭据提取、身份验证、权限判断和失败响应连成稳定链路。完成本节后,你可以在 Route Handler 中同时处理 Bearer 令牌与服务端会话,并正确区分 401 和 403。

学习目标

  • 区分“未认证”和“已认证但无权限”,为它们返回正确状态码
  • 从请求头或 Cookie 中读取凭据,并把验证结果转换成服务端可信身份
  • 设计可替换为真实认证库或会话存储的 Route Handler 鉴权边界

先定义接口的信任边界

Route Handler 收到的请求头、Cookie、查询参数和 JSON 都来自客户端,不能直接把 userId、role 或“已登录”标记当成可信事实。接口应该先验证凭据,再生成服务端身份对象,最后依据这个身份判断能否执行目标操作。

常用约定是:缺少、失效或无法验证的凭据返回 401 Unauthorized;身份已经确认,但权限不足返回 403 Forbidden。业务代码只接收已经验证过的身份,不再重复解析 token 或 Cookie。

让请求先经过鉴权链路

一条清晰的接口链路应按“提取凭据 → 验证身份 → 构造 principal → 检查权限 → 执行业务”推进。这样无论以后接入 JWT、OAuth 会话还是内部服务令牌,业务处理器都不需要知道凭据的具体格式。

Route Handler 接口鉴权链路

下面把演示路由放在 app/api/private/route.ts。管理员权限通过查询参数 admin=1 触发,便于一次验证 401、403 和成功响应。

ts
import type { NextRequest } from 'next/server';

type Principal = {
  userId: string;
  role: 'admin' | 'user';
  source: 'bearer' | 'session';
};

function readPrincipal(request: NextRequest): Principal | null {
  const authorization = request.headers.get('authorization');
  const bearer = authorization?.startsWith('Bearer ')
    ? authorization.slice(7).trim()
    : null;

  // 仅用于本地教学:生产环境应验证签名、有效期或查询认证服务。
  if (bearer && bearer === process.env.DEMO_API_TOKEN) {
    return { userId: 'service-client', role: 'admin', source: 'bearer' };
  }

  const session = request.cookies.get('session')?.value;
  if (session && session === process.env.DEMO_SESSION_TOKEN) {
    return { userId: 'demo-user', role: 'user', source: 'session' };
  }

  return null;
}

export async function GET(request: NextRequest) {
  const principal = readPrincipal(request);

  if (!principal) {
    return Response.json(
      { error: { code: 'UNAUTHORIZED', message: 'Authentication required' } },
      { status: 401, headers: { 'WWW-Authenticate': 'Bearer' } },
    );
  }

  const requiresAdmin = request.nextUrl.searchParams.get('admin') === '1';
  if (requiresAdmin && principal.role !== 'admin') {
    return Response.json(
      { error: { code: 'FORBIDDEN', message: 'Admin permission required' } },
      { status: 403 },
    );
  }

  return Response.json({ data: principal });
}

在 .env.local 中准备仅供本地演示的值,修改后重新启动开发服务器让环境变量生效。

text
DEMO_API_TOKEN=dev-api-token
DEMO_SESSION_TOKEN=dev-session-token

验证时依次发送无凭据、普通会话和管理员 Bearer 令牌三个请求。

bash
curl -i -s http://localhost:3000/api/private
printf '\n'
curl -i -s -H "Cookie: session=dev-session-token" "http://localhost:3000/api/private?admin=1"
printf '\n'
curl -i -s -H "Authorization: Bearer dev-api-token" "http://localhost:3000/api/private?admin=1"

预期输出的关键状态与响应体如下;实际 HTTP 协议版本和附加响应头可能不同。

text
HTTP/1.1 401 Unauthorized
{"error":{"code":"UNAUTHORIZED","message":"Authentication required"}}

HTTP/1.1 403 Forbidden
{"error":{"code":"FORBIDDEN","message":"Admin permission required"}}

HTTP/1.1 200 OK
{"data":{"userId":"service-client","role":"admin","source":"bearer"}}

把真实验证交给认证层

Bearer 令牌至少要验证完整性、有效期以及面向当前服务的签发范围;仅解码 JWT payload 不等于验证。服务端会话则应根据 Cookie 中的随机会话标识查询可信存储,并检查会话是否过期、撤销或更换过权限。

基于 Cookie 的登录通常还要使用 HttpOnly、Secure 和合适的 SameSite 策略;对会改变状态的请求,还要结合应用部署方式评估 CSRF 防护。无论使用哪种方案,都不要让客户端提交角色后由接口“照单全收”。

用失败场景验收鉴权

验收时至少覆盖四种情况:没有凭据、凭据失效、身份有效但权限不足、身份与权限都满足。前三种响应不能泄露签名密钥、数据库错误、用户是否真实存在等内部细节;成功路径则应把可信身份传给后续业务逻辑。

当鉴权逻辑被集中在可复用函数或认证库中,Route Handler 的职责会变得很清楚:先证明“你是谁”,再判断“你能做什么”,最后才执行接口真正的业务。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计接口鉴权

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通