Auth & AuthManager

Auth là lớp xác thực request; AuthManager đăng ký kiểu xác thực và cung cấp JwtService.

1) Tổng quan kiến trúc

2) AuthManager - quản lý xác thực

API	Mô tả
jwt	JwtService - ký/verify JWT. Secret lấy từ options hoặc getDefaultJWTSecret() nếu thiếu.
registerTypes(authType, authConfig)	Đăng ký loại xác thực (tên duy nhất) + class Auth tương ứng + title hiển thị admin.
setStorer(storer)	Bắt buộc trước get(name, ctx): lấy cấu hình authenticator từ DB.
setTokenBlacklistService	Tích hợp blacklist token (revoke).
setTokenControlService	Kiểm soát token (renew, expire).
get(name, ctx)	Tạo instance Auth theo authenticator name + context.
middleware()	Koa middleware xác thực request.

Middleware flow

3) Lớp abstract Auth - chi tiết

skipCheck() - khi nào bỏ qua xác thực

Điều kiện	Ý nghĩa	Tình huống thực tế
ctx.skipAuthCheck = true	Code đánh dấu bỏ qua	Health check endpoint
Không có token + acl = false	Hệ thống tắt ACL	Môi trường dev/test
Action public (ACL allow)	ACL đã cho phép public	Login API, registration

check() - xác thực user

• Trả currentUser (model).
• Lớp con triển khai logic cụ thể:
  • Password auth: check username/password từ DB.
  • SSO auth: validate token từ identity provider.
  • Custom auth: logic tùy plugin.

checkToken() - trạng thái token

Trả về trạng thái:

Status	Ý nghĩa
valid	Token hợp lệ, chưa hết hạn
expired	Token đã hết hạn (cần refresh)
invalid	Token không hợp lệ (signature sai, format lỗi)

4) Mã lỗi (AuthErrorCode)

Code	Ý nghĩa
EMPTY_TOKEN	Request không có bearer token
EXPIRED_TOKEN	Token đã hết hạn
INVALID_TOKEN	Token không hợp lệ
BLOCKED_TOKEN	Token bị blacklist (revoke)
EXPIRED_SESSION	Session đã hết hạn
NOT_EXIST_USER	User trong token không tồn tại

Các lỗi này ném dưới dạng AuthError - client nhận HTTP 401 với error code rõ ràng.

5) JWT Service

• JwtService xử lý sign/verify.
• Có thể gắn blacklist (interface TokenBlacklistService) để revoke token.
• Secret mặc định từ getDefaultJWTSecret() - không nên dùng trong production. Luôn set secret qua env/config.

JWT Secret

Nếu không cung cấp secret qua options, hệ thống dùng getDefaultJWTSecret() - một giá trị cố định không an toàn. Trong production, luôn set AUTH_JWT_SECRET trong biến môi trường.

6) Liên hệ Auth ↔ ACL

Vai trò	Auth	ACL
Trách nhiệm	Xác định ai đang request	Kiểm tra được phép làm gì
Input	Bearer token / session	Role + resource + action
Output	ctx.state.currentUser	allow / deny + fixed params
Có thể bỏ qua?	Có (public action, skipCheck)	Có (allow manager, root role)

• Auth middleware chạy trước ACL middleware trong pipeline.
• Action public theo ACL có thể bỏ qua yêu cầu đăng nhập - xem skipCheck + AllowManager.isPublic.
• Auth chỉ đảm bảo ctx.state.currentUser / token hợp lệ khi có. Không quyết định quyền truy cập.

7) Plugin mở rộng auth

Plugin có thể đăng ký auth type mới:

class MyAuthPlugin extends Plugin {
  async load() {
    this.app.authManager.registerTypes('my-sso', {
      auth: MySSOAuth,  // extends Auth
      title: 'My SSO Provider',
    });
  }
}

MySSOAuth cần implement ít nhất:

• check() - logic xác thực.
• Tùy chọn override skipCheck() nếu có logic đặc biệt.

Đọc tiếp

• Engine ACL - phân quyền sau xác thực
• Server - Application - auth/acl trong vòng đời app
• Luồng dữ liệu & request - vị trí auth trong pipeline