概述
鉴权模块的核心功能是实现用户登录系统,通过 JWT(JSON Web Token)技术实现用户身份验证,并基于 Token 机制实现接口访问控制
在 NestJS 中,鉴权模块的实现通常与 GARDS(Guard、Authentication、Role-based、Dependency Injection、Strategy)机制密切相关
我们需要将 JWT 技术集成进 NestJS 应用中,并结合 Passport.js 提供的认证库完成整个鉴权流程
模块的核心功能包括:
- 用户登录认证
- 生成并返回 JWT
- 使用 JWT 访问受保护的 API 接口
- 基于 Token 的权限控制
- 集成 Passport 和 JWT 库实现认证流程
登录流程与 JWT 基本概念
用户登录时,系统会验证其用户名与密码。验证通过后,系统记录用户信息并返回一个 JWT Token,用户后续请求 API 时,需在请求头中携带该 Token。系统通过解析 Token 来识别用户身份,并控制其访问的权限与范围。
JWT 是一个标准化的 Token 格式,通常由三部分组成:
- Header:包含加密算法及 Token 类型。
- Payload:包含用户信息(如用户名、用户 ID、过期时间等)。
- Signature:服务器对 Header 与 Payload 的签名,确保数据未被篡改。
NestJS 中的鉴权实现结构

参考代码结构图
src/
├── auth/
│ ├── auth.controller.ts
│ ├── auth.service.ts
│ ├── jwt.strategy.ts
│ ├── jwt.guard.ts
│ └── auth.module.ts
├── user/
│ └── user.entity.ts
└── main.ts
或
src/
├── auth/
│ ├── auth.controller.ts
│ ├── auth.service.ts
│ ├── auth.module.ts
│ ├── dto/
│ │ └── login.dto.ts
│ ├── strategies/
│ │ └── jwt.strategy.ts
│ └── guards/
│ └── jwt.guard.ts
在 NestJS 中,鉴权模块的实现主要依赖以下组件:
- Passport.js:提供认证策略(如 LocalStrategy、JWTStrategy)。
- NestJS Passport 模块:封装 Passport.js,使其与 NestJS 的依赖注入机制无缝集成。
- JWT 模块:提供 JWT 的生成与验证工具。
- Guard(守卫):用于路由保护,拦截请求并验证 Token。
- DTO(数据传输对象):用于规范请求与响应数据结构。
- Service:用于处理业务逻辑,如用户校验、Token 签发等。
在 NestJS 中,身份认证(Authentication)是构建安全服务端应用的重要环节。Passport 模块作为主流的身份认证解决方案,提供了多种策略(Strategy)来支持不同场景下的认证逻辑,其中最常用的是 LocalStrategy 和 JwtStrategy
下面结合实际代码示例,详细区分 LocalStrategy 与 JwtStrategy 的工作原理、应用场景及代码实现方式,帮助开发者全面掌握这两种认证策略的核心差异与协同使用方式
什么是 LocalStrategy?
定义与用途
- LocalStrategy 是一种基于用户名和密码的本地认证策略
- 它通常用于用户登录阶段,验证用户提交的账号密码是否正确
- 验证成功后,通常会生成一个 JWT Token 作为后续请求的身份凭证
工作流程
- 用户提交账号密码(如:POST /login)
- 调用 LocalStrategy 的
validate方法,查询数据库验证用户信息 - 验证成功后,生成 JWT Token
- 将 Token 返回给客户端
代码示例
// local.strategy.ts
import { Strategy } from 'passport-local';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { AuthService } from './auth.service';
@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
constructor(private authService: AuthService) {
super();
}
async validate(username: string, password: string): Promise<any> {
const user = await this.authService.validateUser(username, password);
if (!user) {
throw new UnauthorizedException();
}
return user;
}
}
什么是 JwtStrategy
定义与用途
- JwtStrategy 是基于 JWT(JSON Web Token) 的认证策略,主要用于接口请求的 Token 验证
- 它确保请求头中的 Token 是合法的、未被篡改的,并从中提取用户信息
工作流程
- 客户端携带 Token 发起请求(如:GET /profile)
- JwtStrategy 从请求头中提取 Token
- 校验 Token 的签名是否合法
- 解析 Token 中的 Payload(有效载荷),提取用户信息
- 将用户信息挂载到
request.user上,供后续逻辑使用
代码示例
// jwt.strategy.ts
import { ExtractJwt, Strategy } from 'passport-jwt';
import { PassportStrategy } from '@nestjs/passport';
import { Injectable } from '@nestjs/common';
import { jwtConstants } from './constants';
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
constructor() {
super({
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
ignoreExpiration: false,
secretOrKey: jwtConstants.secret,
});
}
async validate(payload: any) {
// payload 包含解码后的用户信息(如:username、sub)
return { userId: payload.sub, username: payload.username };
}
}
LocalStrategy 与 JwtStrategy 的核心区别
| 特性 | LocalStrategy | JwtStrategy |
|---|---|---|
| 认证方式 | 基于用户名+密码 | 基于 Token |
| 使用场景 | 用户登录阶段 | 接口请求时的身份验证 |
| 验证逻辑 | 查询数据库验证用户 | 校验 Token 签名并解析 payload |
| 输出结果 | 返回用户对象 | 返回解析后的用户信息 |
| 是否需要数据库查询 | 需要 | 一般不需要(除非需额外验证) |
| 是否生成 Token | 不生成 | 通常由其配合生成 |
LocalStrategy 与 JwtStrategy 的协作流程
以下是一个完整的认证流程图,展示了从用户登录到接口访问的全过程:
前端请求登录 --> LocalStrategy 验证用户名密码 --> 查询数据库验证用户 --> 成功后返回 JWT Token
用户携带 Token 请求受保护接口 --> JwtStrategy 解析 Token --> 校验签名合法性 --> 提取用户信息 --> 挂载到 request.user --> 控制器使用用户信息
登录控制器示例
// auth.controller.ts
import { Controller, Post, Body, UseGuards } from '@nestjs/common';
import { AuthService } from './auth.service';
@Controller('auth')
export class AuthController {
constructor(private authService: AuthService) {}
@Post('login')
async login(@Body() loginDto: any) {
const user = await this.authService.validateUser(loginDto.username, loginDto.password);
return this.authService.login(user);
}
}
AuthService 示例
// auth.service.ts
import { JwtService } from '@nestjs/jwt';
@Injectable()
export class AuthService {
constructor(
private usersService: UsersService,
private jwtService: JwtService,
) {}
async validateUser(username: string, pass: string): Promise<any> {
const user = await this.usersService.findOne(username);
if (user && user.password === pass) {
return user;
}
return null;
}
async login(user: any) {
const payload = { username: user.username, sub: user.userId };
return {
access_token: this.jwtService.sign(payload),
};
}
}
深入理解 validate 方法的作用
无论是 LocalStrategy 还是 JwtStrategy,validate 方法都是认证逻辑的核心:
- LocalStrategy.validate:负责验证用户名和密码是否匹配数据库中的记录。
- JwtStrategy.validate:负责从 Token 的 payload 中提取用户信息,并返回供后续使用。
注意:Passport 模块会自动将 validate 方法返回的对象挂载到 request.user 上
validate 方法的返回值设计建议
{
id: number,
username: string,
roles: string[]
}
Token 的安全性与签名机制
JWT Token 由三部分组成:
- Header:定义 Token 类型和加密算法
- Payload:存放用户信息(如:username、sub)
- Signature:使用 Secret 签名,确保 Token 未被篡改
// 生成 Token
const token = jwtService.sign({
username: user.username,
sub: user.id,
});
- Token 虽然是明文可读的,但它的签名是不可篡改的
- 只有服务端知道的 Secret 才能验证签名是否合法
LocalStrategy 与 JwtStrategy 的最佳实践
| 场景 | 使用策略 | 说明 |
|---|---|---|
| 用户登录 | LocalStrategy | 验证账号密码,生成 Token |
| 接口访问 | JwtStrategy | 验证 Token,提取用户信息 |
| 权限控制 | 配合 Guard 使用 | 如 @UseGuards(AuthGuard('jwt')) |
| 多策略支持 | 同时注册多个策略 | 可根据业务选择不同策略 |
| Token 刷新 | 自定义逻辑 | 可扩展 JwtStrategy 实现 Token 刷新机制 |
LocalStrategy 与 JwtStrategy 是 NestJS 认证体系中两大支柱。前者负责用户登录阶段的身份验证,后者用于后续接口请求的身份识别。二者协同工作,构成了完整的认证流程
模块开发流程详解
1 ) 用户登录认证流程
- 用户通过前端提交 用户名和密码;
- 后端接收到请求后,在 service 层 查询数据库以验证用户是否存在;
- 验证密码是否匹配;
- 若验证通过,则调用 JWT Service 的 sign 方法 生成 Token;
- 将 Token 作为响应返回给前端。
关键术语强调:
- JWT(JSON Web Token):用于用户身份认证的轻量级 Token。
- Passport:Node.js 中常用的身份验证中间件。
- localStrategy:Passport 提供的本地账号验证策略。
2 ) JWT Token 的生成与签名机制
生成 Token 的关键逻辑:
- 使用 JWT 的 sign 方法;
- 签名内容(payload)通常包括:
userId、username以及可选的过期时间等信息; - 使用 secret key 对 payload 进行加密,确保 Token 安全性;
- 生成的 Token 以
Bearer形式返回给前端。
const payload = { username: user.username, sub: user.id };
const accessToken = this.jwtService.sign(payload);
- Token 的结构解析:
- Header:包含算法(如 HS256)和 Token 类型(如 JWT);
- Payload:包含用户信息和元数据(如
iat和exp); - Signature:由 header 和 payload 组合后使用 secret 加密生成。
3 ) 受保护接口的访问控制(Guard 机制)
-
使用 AuthGuard(JWT) 装饰器保护接口;
-
请求头中必须携带
Authorization: Bearer <token>; -
服务端通过 Passport JWT 模块验证 Token 的合法性;
-
验证成功后,将用户信息附加到
request.user中; -
可在 Controller 中通过
@Req()获取用户信息。@Get('profile') @UseGuards(AuthGuard('jwt')) getProfile(@Request() req) { return req.user; } -
AuthGuard 的作用机制:
- 自动解析 Token;
- 调用
validate方法校验用户合法性; - 若验证通过,则将用户对象附加到
request上
4 ) Passport JWT 模块的集成与配置
安装依赖:
npm install @nestjs/passport passport passport-jwt @nestjs/jwt jwt
npm install @types/passport-jwt --save-dev
配置 JWT 模块:
- 在
AuthModule中导入JwtModule.register; - 设置
secret(建议使用.env文件配置); - 设置 Token 的过期时间(如
60s或86400s); - 设置 Token 提取策略(默认从
Authorizationheader 提取);
import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
@Module({
imports: [
PassportModule.register({ defaultStrategy: 'jwt' }),
JwtModule.register({
secret: process.env.JWT_SECRET,
signOptions: { expiresIn: '86400s' },
}),
],
})
export class AuthModule {}
创建 JWT Strategy:
- 继承
PassportStrategy; - 实现
validate方法,用于校验 Token 中的 payload; - 返回用户对象,供后续接口使用。
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { Injectable } from '@nestjs/common';
@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
constructor() {
super({
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
ignoreExpiration: false,
secretOrKey: process.env.JWT_SECRET,
});
}
async validate(payload: any) {
return { userId: payload.sub, username: payload.username };
}
}
5 ) 登录接口实现与 Token 返回
-
在 Controller 中创建
/login接口; -
调用
authService.validateUser校验用户名密码; -
若通过验证,调用
authService.login返回 Token。@Post('login') async login(@Body() loginDto: LoginDto) { const user = await this.authService.validateUser(loginDto.username, loginDto.password); if (!user) throw new ForbiddenException('用户名或密码错误'); return this.authService.login(user); } -
authService.login方法使用 JWT Service 生成 Token:async login(user: any) { const payload = { username: user.username, sub: user.id }; return { access_token: this.jwtService.sign(payload), }; }
6 )创建守卫 Guard
创建 jwt.guard.ts 文件,用于保护需要认证的接口:
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}
7 )使用守卫保护接口
在控制器中使用守卫,限制未授权用户访问接口:
import { Controller, Get, UseGuards } from '@nestjs/common';
import { JwtAuthGuard } from './jwt.guard';
@Controller('profile')
export class ProfileController {
@UseGuards(JwtAuthGuard)
@Get()
getProfile() {
return { message: 'You are authorized!' };
}
}
用户登录接口实现
创建 auth.controller.ts 与 auth.service.ts,实现用户登录逻辑:
// auth.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { AuthService } from './auth.service';
@Controller('auth')
export class AuthController {
constructor(private authService: AuthService) {}
@Post('login')
async login(@Body() loginDto: any) {
const user = await this.authService.validateUser(loginDto.username, loginDto.password);
if (!user) {
throw new Error('Invalid credentials');
}
return this.authService.login(user);
}
}
// auth.service.ts
import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
@Injectable()
export class AuthService {
constructor(private jwtService: JwtService) {}
async validateUser(username: string, password: string): Promise<any> {
// 实际应从数据库查询用户
const user = { id: 1, username: 'test', password: '123456' };
if (user && user.password === password) {
return user;
}
return null;
}
async login(user: any) {
const payload = { username: user.username, sub: user.id };
return {
access_token: this.jwtService.sign(payload),
};
}
}
安全性与最佳实践
1 )Secret Key 的安全性
- 建议做法:
- 使用强密码生成工具生成至少 64 位的随机字符串
- 使用
.env文件管理配置,避免硬编码 - Secret 密钥应使用高熵值字符串,可通过在线密码生成器生成,推荐长度为 256 位以上
- 不将 Secret Key 提交到 Git 等版本控制系统中
2 ) Token 的有效期管理
- 设置合理的
expiresIn,避免 Token 长期有效 - 建议结合 Refresh Token 实现 Token 刷新机制
- 在前端存储 Token 时,建议使用 HttpOnly Cookie 或 LocalStorage 安全处理
3 ) 数据加密与敏感信息保护
- Token 的 payload 是明文可解码的,不要存放敏感信息(如密码)
- Token 的过期时间不宜过长,可设置为 1 天以内,结合 Refresh Token 机制实现安全续签
- Token 的验证逻辑应由服务端统一处理,前端仅负责存储与传递
- 避免在 Payload 中存储敏感信息,如密码、身份证号等,因 Payload 是公开的, 敏感信息应通过数据库查询获取,而非依赖 Token
- 使用 HTTPS 传输 Token,防止中间人攻击
4 ) 管道(Pipe)与数据校验
-
在登录接口中,使用 ValidationPipe 校验请求体;
-
可自定义管道实现更复杂的校验逻辑;
-
示例:确保用户名长度、密码复杂度等。
@Post('login') @UsePipes(new ValidationPipe()) async login(@Body() loginDto: LoginDto) { // ... }
术语解释与关键技术点
| 术语 | 说明 |
|---|---|
| JWT | JSON Web Token,用于身份验证的标准 Token 格式 |
| Passport.js | Node.js 中流行的认证中间件 |
| Guard | NestJS 提供的路由守卫,用于访问控制 |
| Strategy(策略) | Passport.js 的认证策略,如 LocalStrategy、JWTStrategy |
| Payload | JWT 中存储用户信息的部分 |
| Signature | JWT 的签名部分,用于验证 Token 的合法性 |
| Secret | 用于签名与验证 Token 的密钥 |
| DI(依赖注入) | NestJS 的核心机制之一,用于管理模块间的依赖关系 |
常见问题与解决方案
| 问题 | 解决方案 |
|---|---|
| 登录失败 | 检查用户名密码是否正确,确认数据库查询逻辑 |
| Token 无法解析 | 确认 Token 格式是否为 Bearer,Secret Key 是否正确 |
| Guard 未生效 | 确保已正确导入 PassportModule 和 JwtModule |
| payload 未挂载到 request.user | 检查 validate 方法返回的对象结构 |
| Token 过早过期 | 修改 expiresIn 设置,或实现 Refresh Token 机制 |
总结与扩展建议
- 核心知识回顾
- JWT 是一种基于 Token 的轻量级认证机制;
- Passport 提供了多种策略(如 local、JWT、OAuth);
- NestJS 中通过
AuthGuard和PassportStrategy实现认证; - Token 的安全性依赖于 Secret Key 和 HTTPS
- 进一步学习建议
- 学习 OAuth2、OpenID Connect 等更复杂的认证机制;
- 研究 Refresh Token 的实现与 Token 刷新流程;
- 探索 JWT 的签名算法(如 RS256、HS256);
- 实践多租户或微服务架构下的认证与授权机制。
1990



被折叠的 条评论
为什么被折叠?



