Chi tiết luồng xác thực SMS OTP

Plugin SMS Auth sử dụng luồng OTP (One-Time Password) — không redirect, không SSO truyền thống. User nhập số điện thoại, nhận mã qua SMS, rồi nhập mã để đăng nhập.

Tổng quan luồng

Luồng gồm hai giai đoạn:

1. Request OTP: gọi plugin-verification để gửi mã OTP qua SMS
2. Verify + Sign in: gửi mã OTP cùng credentials để xác thực

Sequence diagram chi tiết

Chi tiết giai đoạn Request OTP

API call

POST /api/verification:create
Content-Type: application/json

{
  "phone": "+84912345678",
  "type": "sms-otp",
  "verifier": "twilio-sms"
}

Xử lý phía server

1. Plugin-verification nhận request
2. Tìm verifier theo tên → lấy cấu hình provider
3. Tạo mã OTP ngẫu nhiên (thường 6 chữ số)
4. Tạo uuid ngẫu nhiên → lưu vào otpRecords table với TTL
5. Gọi SMS provider API để gửi tin nhắn
6. Trả về uuid cho client

OTP record

Field	Mô tả
uuid	Định danh duy nhất của phiên OTP
code	Mã OTP (hash hoặc plaintext tùy cấu hình)
phone	Số điện thoại nhận
expiresAt	Thời điểm hết hạn
used	Đã sử dụng hay chưa

Chi tiết giai đoạn Verify + Sign in

API call

POST /api/auth:signIn
Content-Type: application/json
X-Authenticator: sms-{name}

{
  "phone": "+84912345678",
  "uuid": "xxx-xxx-xxx",
  "code": "123456"
}

Xử lý phía server

1. Plugin SMS Auth nhận request
2. Gọi verificationManager.verify(uuid, code):
   • Tìm OTP record theo uuid
   • So sánh code
   • Kiểm tra hết hạn (expiresAt)
   • Đánh dấu đã sử dụng
3. Tìm local user theo số điện thoại
4. Tạo user mới nếu autoSignup = true và user chưa tồn tại
5. Tạo session token và trả về

Xử lý lỗi

Lỗi	Nguyên nhân	HTTP Status
Verifier not found	public.verifier sai tên	500
SMS send failed	Provider API lỗi	500
Invalid code	Mã OTP không khớp	401
Code expired	Quá thời hạn TTL	401
User not found + autoSignup=false	SĐT chưa đăng ký	401