Cấu hình chi tiết — Two-Factor Authentication

Cấu trúc cấu hình

Plugin lưu cấu hình trong collection twoFactorAuthSettings với field options kiểu jsonb:

typescript

type TwoFactorAuthSettings = {
  enforce: boolean;     // Bắt buộc 2FA cho tất cả user
  verifiers: string[];  // Danh sách tên verifier được dùng
};

Giá trị mặc định

json

{
  "enforce": false,
  "verifiers": []
}

Bảng cấu hình

Tham số	Kiểu	Mặc định	Mô tả
`enforce`	`boolean`	`false`	Bắt buộc 2FA — khi bật, tất cả user phải hoàn thành 2FA để đăng nhập
`verifiers`	`string[]`	`[]`	Danh sách tên verifier được phép dùng cho 2FA (ví dụ: `["sms-otp-verifier", "email-otp-verifier"]`)

Verification scene

Plugin đăng ký verification scene '2fa' với các quy tắc:

Scene rules

typescript

verificationManager.addSceneRule((scene, type) => {
  return scene === '2fa' && ['sms-otp', 'email-otp'].includes(type);
});

Chỉ verifier loại sms-otp hoặc email-otp được chấp nhận cho scene 2FA. Các loại khác sẽ bị từ chối.

Scene actions

Action	Mô tả	Cấu hình đặc biệt
`twoFactorAuth:bind`	Liên kết verifier với user	`manual: true` — user tự cung cấp thông tin liên kết
`twoFactorAuth:verify`	Xác minh mã 2FA	`onVerifySuccess` — tạo token mới cho user

Cơ chế cache

Plugin cache cấu hình 2FA để tránh đọc database mỗi lần kiểm tra:

Cache key: 2fa:settings

Cache được tự động cập nhật khi settings thay đổi (thông qua event twoFactorAuthSettings.afterSave):

typescript

this.db.on('twoFactorAuthSettings.afterSave', async (model) => {
  const options = model.get('options');
  const cacheOptions = await this.app.cache.get(CACHE_KEY);
  await this.app.cache.set(CACHE_KEY, { ...cacheOptions, ...options });
});

Cấu hình qua API

Lấy cấu hình hiện tại

typescript

const res = await agent.resource('twoFactorAuthSettings').get();
const settings = res.body.data.options;
// { enforce: false, verifiers: [] }

Cập nhật cấu hình

typescript

await agent.resource('twoFactorAuthSettings').update({
  values: {
    options: {
      enforce: true,
      verifiers: ['sms-verifier', 'email-verifier'],
    },
  },
});

Cảnh báo

Khi bật enforce: true, tất cả user sẽ bị yêu cầu hoàn thành 2FA ở lần đăng nhập tiếp theo. Đảm bảo đã cấu hình ít nhất 1 verifier trước khi bật enforce.

ACL — Phân quyền

Resource	Action	Quyền	Mô tả
`twoFactorAuth`	`sessionCheck`	`public`	Ai cũng kiểm tra được (cần 2FA token)
`twoFactorAuth`	`verify`	`public`	Xác minh mã 2FA
`twoFactorAuth`	`bind`	`public`	Liên kết verifier
`twoFactorAuthSettings`	`*`	Admin snippet	Quản lý cấu hình 2FA

Lưu ý

Các action sessionCheck, verify, bind được đặt ACL public nhưng vẫn yêu cầu 2FA token hợp lệ (token tạm thời từ bước đăng nhập). Không phải bất kỳ ai cũng truy cập được.

Phương thức 2FA hỗ trợ

Phương thức	Verification type	Yêu cầu
SMS OTP	`sms-otp`	Cấu hình SMS provider trong plugin-verification
Email OTP	`email-otp`	Cấu hình SMTP trong plugin-verification

Mẹo

Để thêm phương thức 2FA mới, tạo verification type trong plugin-verification và đảm bảo scene rule chấp nhận type đó.

Middleware

Plugin đăng ký 2 middleware:

`twoFactorAuthSettingsActions`

Middleware xử lý các action liên quan đến cấu hình 2FA settings. Chạy trước handler chính.

`twoFactorAuth`

Middleware chính chặn request sau khi đăng nhập thành công. Kiểm tra user có cần hoàn thành 2FA không.