Giao diện

FAQ & Troubleshooting — SMS Auth ​

Các câu hỏi thường gặp và cách xử lý sự cố khi sử dụng plugin SMS Auth.

Lỗi "Verification plugin not found" ​

Triệu chứng: Không thể gửi OTP, server báo lỗi liên quan đến verification plugin.

Nguyên nhân: Plugin @digiforce-nc/plugin-verification chưa được cài đặt hoặc chưa kích hoạt.

Giải pháp:

  1. Kiểm tra plugin-verification đã có trong danh sách plugins
  2. Kích hoạt plugin nếu chưa bật
  3. Khởi động lại server Digiforce sau khi cài đặt

Bắt buộc

Plugin SMS Auth không thể hoạt động nếu thiếu plugin-verification. Đây là peer dependency bắt buộc.

Số điện thoại chưa đăng ký ​

Triệu chứng: User nhập mã OTP đúng nhưng nhận lỗi "User not found" hoặc "Số điện thoại chưa đăng ký".

Nguyên nhân: autoSignup = false và số điện thoại chưa có trong hệ thống.

Giải pháp:

  • Cách 1: Bật autoSignup = true trong authenticator settings
  • Cách 2: Admin tạo user trước với số điện thoại khớp (format quốc tế: +84912345678)

OTP không nhận được ​

Triệu chứng: Nhấn "Gửi mã" nhưng không nhận SMS.

Kiểm tra:

  1. Provider cấu hình đúng chưa? — Kiểm tra credentials (API key, token...) trong verifier settings
  2. Số điện thoại hợp lệ? — Đảm bảo format quốc tế (+84..., +1...)
  3. Provider có lỗi không? — Kiểm tra log gửi SMS trên dashboard của provider (Twilio Console, Aliyun SMS...)
  4. Rate limit? — Một số provider giới hạn số SMS gửi trong khoảng thời gian ngắn
  5. Balance đủ không? — Kiểm tra số dư tài khoản SMS provider

Migration từ phiên bản cũ ​

verificator → verifier ​

Nếu nâng cấp từ phiên bản cũ sử dụng tham số verificator:

  • Plugin tự động migration sang verifier
  • Nếu cấu hình qua API, cần cập nhật tên tham số thủ công

smsAuthEnabled → authenticators ​

Phiên bản cũ dùng cờ smsAuthEnabled trong system settings:

  • Plugin chạy migration tự động khi khởi động
  • Tạo authenticator mới từ cấu hình cũ
  • Sau migration, quản lý qua Settings → Authentication
  • Nếu migration không tự chạy, tạo authenticator SMS mới thủ công

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

Nguyên nhân: TTL của OTP cấu hình trong verifier (plugin-verification) quá ngắn.

Giải pháp: Điều chỉnh TTL trong cấu hình verifier. Giá trị khuyến nghị: 5-10 phút.

Gửi OTP thành công nhưng verify thất bại ​

Kiểm tra:

  1. uuid có khớp không? — uuid trả về từ verification:create phải gửi lại chính xác trong auth:signIn
  2. Mã OTP đúng không? — Phân biệt số 0 và chữ O, số 1 và chữ l
  3. Hết hạn chưa? — Kiểm tra thời gian giữa nhận SMS và nhập mã
  4. Đã sử dụng chưa? — Mỗi mã OTP chỉ dùng được một lần