Giao diện

Câu hỏi thường gặp (FAQ) — Verification ​

Cấu hình ​

Email gửi OTP vào thư rác (spam)? ​

Giải pháp:

  • Cấu hình SPF, DKIM, DMARC cho domain gửi
  • Sử dụng dịch vụ email chuyên nghiệp (SendGrid, Amazon SES) thay vì SMTP cá nhân
  • Kiểm tra nội dung email không chứa từ khóa spam
  • Đảm bảo domain gửi có reputation tốt

SMS provider nào được hỗ trợ sẵn? ​

Plugin đăng ký sẵn 2 provider:

ProviderTypeMô tả
Aliyun SMSaliyun-smsSMS qua Alibaba Cloud — phổ biến ở châu Á
Tencent SMStencent-smsSMS qua Tencent Cloud

Để thêm provider khác (Twilio, Vonage...), đăng ký qua smsOTPProviderManager.registerProvider().

Có thể dùng nhiều provider cùng lúc không? ​

Có. Tạo nhiều verifier, mỗi cái dùng provider khác nhau. Khi cần xác minh, chọn verifier phù hợp.

Rate limiting hoạt động thế nào? ​

Plugin sử dụng Counter từ @digiforce-nc/cache:

  • Counter theo dõi số lần gửi SMS theo prefix sms-otp:attempts
  • Kết hợp với lockManager để an toàn khi nhiều instance cùng chạy
  • Reset khi cache expire hoặc server restart (nếu dùng in-memory)

Cảnh báo

Nếu dùng in-memory cache, restart server sẽ reset counter — user có thể gửi SMS vượt giới hạn. Khuyến nghị dùng Redis cho production.

Sử dụng ​

Người dùng không nhận được mã OTP? ​

Kiểm tra theo thứ tự:

  1. Provider đã cấu hình đúng? Kiểm tra credentials (access key, secret)
  2. Số điện thoại đúng format? Cần đúng mã quốc gia (ví dụ: +84912345678)
  3. Template SMS đã duyệt? Với Aliyun/Tencent, template SMS cần được duyệt trước khi gửi
  4. Rate limit? User có thể đã gửi quá nhiều lần — chờ cooldown
  5. Log server: Kiểm tra log để xem lỗi từ provider

Mã OTP hết hạn quá nhanh? ​

Tùy chỉnh thời gian hết hạn trong cấu hình verifier hoặc SMS OTP provider. Mặc định thường là 5 phút.

Bị khóa vì nhập sai quá nhiều lần? ​

Chờ hết thời gian cooldown rồi thử lại. Admin có thể xóa counter trong cache hoặc database để reset.

Kỹ thuật ​

Plugin nào phụ thuộc vào plugin-verification? ​

PluginCách sử dụng
plugin-two-factor-authenticationĐăng ký scene '2fa', dùng verifiers cho xác thực hai yếu tố
plugin-auth-smsĐăng ký scene 'auth-sms', xác thực đăng nhập bằng SMS

VerificationManager middleware làm gì? ​

Middleware chặn các action đã đăng ký trong scenes. Khi action cần xác minh:

  1. Middleware kiểm tra request có verification token hợp lệ không
  2. Nếu không → trả về yêu cầu xác minh với danh sách verifiers khả dụng
  3. Nếu có → cho phép tiếp tục

bindingRequired nghĩa là gì? ​

Khi bindingRequired: true trên verification type:

  • User phải liên kết (bind) verifier trước khi có thể xác minh
  • Ví dụ: SMS OTP yêu cầu user liên kết số điện thoại trước

Khi bindingRequired: false:

  • User không cần liên kết trước — cung cấp thông tin ngay khi cần xác minh
  • Ví dụ: Email OTP gửi mã đến email đã biết

publicCreate có an toàn không? ​

smsOTP:publicCreate cho phép gửi SMS không cần đăng nhập — cần thiết cho luồng đăng ký và quên mật khẩu. Để bảo mật:

  • Dùng rate limiting (counter) để giới hạn số lần gửi
  • Thêm CAPTCHA phía client trước khi gọi
  • Giám sát log để phát hiện abuse