Hướng dẫn cài đặt — Verification

Yêu cầu

Thành phần	Yêu cầu
Digiforce Server	Đang chạy bình thường
SMS Provider	Ít nhất 1 SMS provider (Aliyun SMS hoặc Tencent SMS)
Cache	Redis hoặc in-memory cache cho rate limiting

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-verification và bật.

Hoặc kích hoạt qua dòng lệnh:

bash

yarn pm enable plugin-verification

Bước 2: Cấu hình SMS Provider

Plugin hỗ trợ sẵn 2 SMS provider:

Aliyun SMS

Cấu hình qua biến môi trường khi cài đặt lần đầu:

bash

DEFAULT_SMS_VERIFY_CODE_PROVIDER=aliyun-default
INIT_ALI_SMS_ACCESS_KEY=your-access-key
INIT_ALI_SMS_ACCESS_KEY_SECRET=your-secret
INIT_ALI_SMS_ENDPOINT=dysmsapi.aliyuncs.com
INIT_ALI_SMS_VERIFY_CODE_TEMPLATE=SMS_12345678
INIT_ALI_SMS_VERIFY_CODE_SIGN=YourSignName

Hoặc cấu hình qua UI: Settings → Verification → SMS Providers → Add Provider

Trường	Mô tả
`accessKeyId`	Access Key ID từ Aliyun Console
`accessKeySecret`	Access Key Secret
`endpoint`	API endpoint (mặc định: `dysmsapi.aliyuncs.com`)
`sign`	Tên chữ ký SMS (đã đăng ký trên Aliyun)
`template`	Mã template SMS (đã đăng ký trên Aliyun)

Tencent SMS

Cấu hình tương tự qua UI hoặc API, chọn provider type là tencent-sms.

Bước 3: Tạo Verifier

Verifier là cấu hình xác minh cụ thể. Ví dụ: "SMS OTP qua Aliyun" là 1 verifier.

Vào Settings → Verification → Verifiers → Add:

Trường	Mô tả
`name`	Tên duy nhất (ví dụ: `sms-otp-aliyun`)
`title`	Tên hiển thị (ví dụ: "SMS Verification")
`verificationType`	Loại xác minh (ví dụ: `sms-otp`)
`options`	Cấu hình riêng cho verifier

Bước 4: Kiểm tra

Test gửi SMS OTP

typescript

const res = await agent.resource('smsOTP').create({
  values: {
    phone: '+84912345678',
  },
});

Test xác minh

Luồng xác minh phụ thuộc vào scene đăng ký. Ví dụ với 2FA:

Đăng nhập → nhận 2FA token
Gọi twoFactorAuth:sessionCheck → nhận danh sách verifiers
Chọn verifier → nhận mã SMS
Nhập mã → xác minh thành công

Kiến trúc VerificationManager

Verification Types

Mỗi type đăng ký bao gồm:

typescript

verificationManager.registerVerificationType('sms-otp', {
  title: tval('SMS OTP'),
  description: tval('Mã xác minh qua SMS'),
  bindingRequired: true,         // User phải liên kết số điện thoại trước
  verification: SMSOTPVerification,  // Class xử lý gửi/xác minh
});

Scenes

Scene là kịch bản xác minh. Mỗi scene định nghĩa:

Actions: Những action nào cần xác minh trong scene này
getVerifiers: Hàm lấy danh sách verifiers cho scene

Scene Rules

Quy tắc xác định scene nào chấp nhận verification type nào:

typescript

verificationManager.addSceneRule(
  (scene, verificationType) =>
    ['auth-sms', 'unbind-verifier'].includes(scene) 
    && verificationType === 'sms-otp'
);

Rate Limiting

Plugin sử dụng Counter từ @digiforce-nc/cache để giới hạn số lần gửi SMS:

typescript

this.smsOTPCounter = await this.app.cacheManager.createCounter(
  {
    name: 'smsOTPCounter',
    prefix: 'sms-otp:attempts',
  },
  this.app.lockManager,
);

Counter kết hợp với lockManager để đảm bảo an toàn trong môi trường đa instance.

Lưu ý quan trọng

Plugin là dependency bắt buộc cho plugin-two-factor-authentication và plugin-auth-sms
SMS provider cần cấu hình đúng credentials — test trước khi đưa vào production
Rate limiting dựa trên cache — nếu dùng in-memory cache, restart server sẽ reset counter
smsOTP:publicCreate cho phép tạo OTP không cần đăng nhập — cần cẩn thận với rate limiting