Authentication (Xác thực)

Xác thực (authentication) là một phần thiết yếu của hầu hết ứng dụng. Có rất nhiều cách tiếp cận và chiến lược khác nhau để xử lý xác thực. Cách tiếp cận cho mỗi dự án phụ thuộc vào yêu cầu cụ thể của ứng dụng đó. Chương này trình bày một số cách tiếp cận có thể điều chỉnh cho phù hợp với nhiều loại yêu cầu khác nhau.

Hãy cùng làm rõ yêu cầu của chúng ta. Với use case này, client sẽ bắt đầu bằng việc xác thực bằng username và password. Sau khi xác thực thành công, server sẽ phát hành một JWT có thể được gửi dưới dạng bearer token trong header authorization ở các request tiếp theo để chứng minh đã xác thực. Chúng ta cũng sẽ tạo một route được bảo vệ, chỉ cho phép truy cập với những request có JWT hợp lệ.

Chúng ta sẽ bắt đầu với yêu cầu đầu tiên: xác thực người dùng. Sau đó mở rộng thêm bằng việc phát hành JWT. Cuối cùng, chúng ta sẽ tạo một route được bảo vệ để kiểm tra JWT hợp lệ trên request.

Tạo module xác thực (authentication module)

Chúng ta bắt đầu bằng việc generate một AuthModule, và trong đó là AuthService và AuthController. AuthService dùng để triển khai logic xác thực, còn AuthController dùng để expose các endpoint xác thực.

$ nest g module auth
$ nest g controller auth
$ nest g service auth

Khi triển khai AuthService, chúng ta sẽ thấy hữu ích khi đóng gói các thao tác liên quan đến user vào một UsersService, vậy hãy generate module và service đó ngay bây giờ:

$ nest g module users
$ nest g service users

Thay nội dung mặc định của các file vừa generate như dưới đây. Với app mẫu này, UsersService chỉ đơn giản duy trì một danh sách user hard-code trong bộ nhớ, cùng một method find để tìm một user theo username. Trong ứng dụng thực tế, đây là nơi bạn sẽ xây dựng user model và lớp persistence (lưu trữ dữ liệu), sử dụng thư viện bạn chọn (ví dụ: TypeORM, Sequelize, Mongoose, v.v.).

import { Injectable } from '@nestjs/common';

// This should be a real class/interface representing a user entity
export type User = any;

@Injectable()
export class UsersService {
  private readonly users = [
    {
      userId: 1,
      username: 'john',
      password: 'changeme',
    },
    {
      userId: 2,
      username: 'maria',
      password: 'guess',
    },
  ];

  async findOne(username: string): Promise<User | undefined> {
    return this.users.find(user => user.username === username);
  }
}

import { Injectable } from '@nestjs/common';

@Injectable()
export class UsersService {
  constructor() {
    this.users = [
      {
        userId: 1,
        username: 'john',
        password: 'changeme',
      },
      {
        userId: 2,
        username: 'maria',
        password: 'guess',
      },
    ];
  }

  async findOne(username) {
    return this.users.find(user => user.username === username);
  }
}

Trong UsersModule, thay đổi duy nhất cần thiết là thêm UsersService vào mảng exports của decorator @Module để nó có thể được nhìn thấy từ bên ngoài module này (chúng ta sẽ dùng đến nó trong AuthService ngay sau đây).

import { Module } from '@nestjs/common';
import { UsersService } from './users.service.js';

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

import { Module } from '@nestjs/common';
import { UsersService } from './users.service.js';

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

Triển khai endpoint “Sign in” (đăng nhập)

AuthService có nhiệm vụ lấy thông tin user và xác minh password. Chúng ta tạo method signIn() cho mục đích này. Trong đoạn code dưới đây, ta dùng spread operator (toán tử trải) tiện lợi của ES6 để loại bỏ property password khỏi object user trước khi trả về. Đây là thực hành phổ biến khi trả về object user, vì bạn không muốn để lộ các field nhạy cảm như password hay các key bảo mật khác.

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { UsersService } from '../users/users.service.js';

@Injectable()
export class AuthService {
  constructor(private readonly usersService: UsersService) {}

  async signIn(username: string, pass: string): Promise<any> {
    const user = await this.usersService.findOne(username);
    if (user?.password !== pass) {
      throw new UnauthorizedException();
    }
    const { password, ...result } = user;
    // TODO: Generate a JWT and return it here
    // instead of the user object
    return result;
  }
}

import { Injectable, Dependencies, UnauthorizedException } from '@nestjs/common';
import { UsersService } from '../users/users.service.js';

@Injectable()
@Dependencies(UsersService)
export class AuthService {
  constructor(usersService) {
    this.usersService = usersService;
  }

  async signIn(username: string, pass: string) {
    const user = await this.usersService.findOne(username);
    if (user?.password !== pass) {
      throw new UnauthorizedException();
    }
    const { password, ...result } = user;
    // TODO: Generate a JWT and return it here
    // instead of the user object
    return result;
  }
}

Bây giờ, cập nhật AuthModule để import UsersModule.

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service.js';
import { AuthController } from './auth.controller.js';
import { UsersModule } from '../users/users.module.js';

@Module({
  imports: [UsersModule],
  providers: [AuthService],
  controllers: [AuthController],
})
export class AuthModule {}

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service.js';
import { AuthController } from './auth.controller.js';
import { UsersModule } from '../users/users.module.js';

@Module({
  imports: [UsersModule],
  providers: [AuthService],
  controllers: [AuthController],
})
export class AuthModule {}

Với thay đổi này, hãy mở AuthController và thêm method signIn() vào đó. Method này sẽ được client gọi để xác thực user. Nó sẽ nhận username và password trong request body, và trả về một JWT token nếu user xác thực thành công.

import { Body, Controller, Post, HttpCode, HttpStatus } from '@nestjs/common';
import { AuthService } from './auth.service.js';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @HttpCode(HttpStatus.OK)
  @Post('login')
  signIn(@Body() signInDto: Record<string, any>) {
    return this.authService.signIn(signInDto.username, signInDto.password);
  }
}

JWT token

Chúng ta đã sẵn sàng chuyển sang phần JWT của hệ thống xác thực. Hãy cùng rà soát và làm rõ thêm yêu cầu:

• Cho phép user xác thực bằng username/password, trả về JWT để dùng cho các lần gọi tiếp theo tới các API endpoint được bảo vệ. Chúng ta đã đi được nửa đường để đáp ứng yêu cầu này. Để hoàn tất, ta cần viết code phát hành JWT.
• Tạo các API route được bảo vệ dựa trên việc có JWT hợp lệ dưới dạng bearer token hay không

Chúng ta cần cài thêm một package để hỗ trợ yêu cầu JWT:

$ npm install --save @nestjs/jwt

Để giữ các service của mình được module hóa rõ ràng, chúng ta sẽ xử lý việc generate JWT trong authService. Mở file auth.service.ts trong thư mục auth, inject JwtService, và cập nhật method signIn để generate một JWT token như dưới đây:

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { UsersService } from '../users/users.service.js';
import { JwtService } from '@nestjs/jwt';

@Injectable()
export class AuthService {
  constructor(
    private usersService: UsersService,
    private jwtService: JwtService
  ) {}

  async signIn(
    username: string,
    pass: string,
  ): Promise<{ access_token: string }> {
    const user = await this.usersService.findOne(username);
    if (user?.password !== pass) {
      throw new UnauthorizedException();
    }
    const payload = { sub: user.userId, username: user.username };
    return {
      // 💡 Ở đây, secret key dùng để ký (sign) payload JWT
      // chính là key đã được truyền vào JwtModule
      access_token: await this.jwtService.signAsync(payload),
    };
  }
}

import { Injectable, Dependencies, UnauthorizedException } from '@nestjs/common';
import { UsersService } from '../users/users.service.js';
import { JwtService } from '@nestjs/jwt';

@Dependencies(UsersService, JwtService)
@Injectable()
export class AuthService {
  constructor(usersService, jwtService) {
    this.usersService = usersService;
    this.jwtService = jwtService;
  }

  async signIn(username, pass) {
    const user = await this.usersService.findOne(username);
    if (user?.password !== pass) {
      throw new UnauthorizedException();
    }
    const payload = { username: user.username, sub: user.userId };
    return {
      // 💡 Ở đây, secret key dùng để ký (sign) payload JWT
      // chính là key đã được truyền vào JwtModule
      access_token: await this.jwtService.signAsync(payload),
    };
  }
}

Chúng ta đang dùng thư viện @nestjs/jwt, thư viện này cung cấp hàm signAsync() để generate JWT từ một tập con các property của object user, sau đó trả về dưới dạng một object đơn giản chỉ có một property access_token. Lưu ý: chúng ta chọn tên property sub để chứa giá trị userId cho nhất quán với chuẩn JWT.

Giờ chúng ta cần cập nhật AuthModule để import các dependency mới và cấu hình JwtModule.

Đầu tiên, tạo file constants.ts trong thư mục auth, và thêm code sau:

export const jwtConstants = {
  secret: 'DO NOT USE THIS VALUE. INSTEAD, CREATE A COMPLEX SECRET AND KEEP IT SAFE OUTSIDE OF THE SOURCE CODE.',
};

export const jwtConstants = {
  secret: 'DO NOT USE THIS VALUE. INSTEAD, CREATE A COMPLEX SECRET AND KEEP IT SAFE OUTSIDE OF THE SOURCE CODE.',
};

Chúng ta sẽ dùng file này để chia sẻ key giữa các bước ký (signing) và xác minh (verifying) JWT.

Bây giờ, mở auth.module.ts trong thư mục auth và cập nhật như sau:

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service.js';
import { UsersModule } from '../users/users.module.js';
import { JwtModule } from '@nestjs/jwt';
import { AuthController } from './auth.controller.js';
import { jwtConstants } from './constants.js';

@Module({
  imports: [
    UsersModule,
    JwtModule.register({
      global: true,
      secret: jwtConstants.secret,
      signOptions: { expiresIn: '60s' },
    }),
  ],
  providers: [AuthService],
  controllers: [AuthController],
  exports: [AuthService],
})
export class AuthModule {}

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service.js';
import { UsersModule } from '../users/users.module.js';
import { JwtModule } from '@nestjs/jwt';
import { AuthController } from './auth.controller.js';
import { jwtConstants } from './constants.js';

@Module({
  imports: [
    UsersModule,
    JwtModule.register({
      global: true,
      secret: jwtConstants.secret,
      signOptions: { expiresIn: '60s' },
    }),
  ],
  providers: [AuthService],
  controllers: [AuthController],
  exports: [AuthService],
})
export class AuthModule {}

Chúng ta cấu hình JwtModule bằng register(), truyền vào một configuration object. Xem tại đây để biết thêm về JwtModule của Nest, và tại đây để biết chi tiết các option cấu hình khả dụng.

Hãy thử test các route của chúng ta bằng cURL. Bạn có thể test với bất kỳ object user nào hard-code trong UsersService.

$ # POST to /auth/login
$ curl -X POST http://localhost:3000/auth/login -d '{"username": "john", "password": "changeme"}' -H "Content-Type: application/json"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
$ # Note: above JWT truncated

Triển khai authentication guard (guard xác thực)

Giờ chúng ta có thể xử lý yêu cầu cuối cùng: bảo vệ endpoint bằng cách yêu cầu request phải có JWT hợp lệ. Chúng ta sẽ làm điều này bằng cách tạo một AuthGuard để bảo vệ các route.

import {
  CanActivate,
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { Request } from 'express';

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly jwtService: JwtService) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractTokenFromHeader(request);
    if (!token) {
      throw new UnauthorizedException();
    }
    try {
      // 💡 Ở đây, secret key dùng để verify (xác minh) payload JWT
      // chính là key đã được truyền vào JwtModule
      const payload = await this.jwtService.verifyAsync(token);
      // 💡 Chúng ta gán payload vào request object ở đây
      // để có thể truy cập nó trong các route handler
      request['user'] = payload;
    } catch {
      throw new UnauthorizedException();
    }
    return true;
  }

  private extractTokenFromHeader(request: Request): string | undefined {
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

Giờ ta có thể triển khai route được bảo vệ và đăng ký AuthGuard để bảo vệ nó.

Mở file auth.controller.ts và cập nhật như dưới đây:

import {
  Body,
  Controller,
  Get,
  HttpCode,
  HttpStatus,
  Post,
  Request,
  UseGuards
} from '@nestjs/common';
import { AuthGuard } from './auth.guard.js';
import { AuthService } from './auth.service.js';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @HttpCode(HttpStatus.OK)
  @Post('login')
  signIn(@Body() signInDto: Record<string, any>) {
    return this.authService.signIn(signInDto.username, signInDto.password);
  }

  @UseGuards(AuthGuard)
  @Get('profile')
  getProfile(@Request() req) {
    return req.user;
  }
}

Chúng ta áp dụng AuthGuard vừa tạo cho route GET /profile để route này được bảo vệ.

Đảm bảo app đang chạy, và test các route bằng cURL.

$ # GET /profile
$ curl http://localhost:3000/auth/profile
{"statusCode":401,"message":"Unauthorized"}

$ # POST /auth/login
$ curl -X POST http://localhost:3000/auth/login -d '{"username": "john", "password": "changeme"}' -H "Content-Type: application/json"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2Vybm..."}

$ # GET /profile using access_token returned from previous step as bearer code
$ curl http://localhost:3000/auth/profile -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2Vybm..."
{"sub":1,"username":"john","iat":...,"exp":...}

Lưu ý rằng trong AuthModule, chúng ta đã cấu hình JWT có thời hạn hết hiệu lực (expiration) là 60 giây. Đây là thời hạn quá ngắn, và việc xử lý chi tiết chuyện hết hạn token và refresh (làm mới) token nằm ngoài phạm vi bài viết này. Tuy nhiên, chúng ta chọn thời hạn ngắn như vậy để minh họa một đặc tính quan trọng của JWT. Nếu bạn đợi 60 giây sau khi xác thực rồi mới gọi GET /auth/profile, bạn sẽ nhận về response 401 Unauthorized. Đó là vì @nestjs/jwt tự động kiểm tra thời gian hết hạn của JWT, giúp bạn không phải tự làm việc đó trong ứng dụng.

Vậy là chúng ta đã hoàn thành việc triển khai xác thực JWT. Các client JavaScript (như Angular/React/Vue) và các app JavaScript khác giờ có thể xác thực và giao tiếp an toàn với API Server của chúng ta.

Kích hoạt xác thực toàn cục (globally)

Nếu phần lớn endpoint của bạn cần được bảo vệ theo mặc định, bạn có thể đăng ký authentication guard làm global guard (guard toàn cục), và thay vì dùng decorator @UseGuards() trên từng controller, bạn chỉ cần đánh dấu route nào nên là public (công khai).

Đầu tiên, đăng ký AuthGuard làm global guard bằng cấu trúc sau (ở bất kỳ module nào, ví dụ trong AuthModule):

providers: [
  {
    provide: APP_GUARD,
    useClass: AuthGuard,
  },
],

Với thay đổi này, Nest sẽ tự động gắn (bind) AuthGuard vào tất cả endpoint.

Giờ chúng ta cần cung cấp một cơ chế để khai báo route nào là public. Để làm điều này, chúng ta có thể tạo một custom decorator dùng decorator factory function SetMetadata.

import { SetMetadata } from '@nestjs/common';

export const IS_PUBLIC_KEY = 'isPublic';
export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);

Trong file trên, chúng ta export hai constant. Một là metadata key tên là IS_PUBLIC_KEY, và một là decorator mới mà chúng ta gọi là Public (bạn có thể đặt tên khác như SkipAuth hay AllowAnon, tùy theo dự án của bạn).

Có @Public() decorator rồi, chúng ta có thể dùng nó để đánh dấu bất kỳ method nào, như sau:

@Public()
@Get()
findAll() {
  return [];
}

Cuối cùng, chúng ta cần AuthGuard trả về true khi tìm thấy metadata "isPublic". Để làm điều này, ta sẽ dùng class Reflector (đọc thêm tại đây).

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly jwtService: JwtService, private reflector: Reflector) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);
    if (isPublic) {
      // 💡 Xem điều kiện này
      return true;
    }

    const request = context.switchToHttp().getRequest();
    const token = this.extractTokenFromHeader(request);
    if (!token) {
      throw new UnauthorizedException();
    }
    try {
      // 💡 Ở đây, secret key dùng để verify (xác minh) payload JWT
      // chính là key đã được truyền vào JwtModule
      const payload = await this.jwtService.verifyAsync(token);
      // 💡 Chúng ta gán payload vào request object ở đây
      // để có thể truy cập nó trong các route handler
      request['user'] = payload;
    } catch {
      throw new UnauthorizedException();
    }
    return true;
  }

  private extractTokenFromHeader(request: Request): string | undefined {
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
    return type === 'Bearer' ? token : undefined;
  }
}

Tích hợp Passport

Passport là thư viện xác thực node.js phổ biến nhất, được cộng đồng biết đến rộng rãi và đã được dùng thành công trong nhiều ứng dụng production. Việc tích hợp thư viện này với ứng dụng Nest rất đơn giản nhờ module @nestjs/passport.

Để tìm hiểu cách tích hợp Passport với NestJS, xem chương này.

Ví dụ

Bạn có thể tìm phiên bản đầy đủ của code trong chương này tại đây.