Chuyển tới nội dung chính

Use case: đăng ký, xác thực và đăng nhập

Actor và mục đích​

ActorMục đích
KháchTạo tài khoản và đăng nhập
Người dùngĐăng nhập lại, quên và đặt lại mật khẩu, đổi mật khẩu

Precondition và postcondition​

Đăng kýĐăng nhập
PreconditionEmail chưa dùng bởi tài khoản chưa xóaTài khoản đã kích hoạt, không bị khóa, không chờ xóa
PostconditionTài khoản NORMAL USER isActive = false; OTP gửi qua emailCó phiên mới; client giữ access token, trình duyệt giữ cookie refresh token

Luồng chính: đăng ký bằng email​

  1. Khách gửi tên, email, mật khẩu (POST /auth/register, 5 lần mỗi giờ).
  2. Hệ thống băm mật khẩu bằng bcrypt, tạo tài khoản chưa kích hoạt với verificationExpires 15 phút, sinh OTP 6 chữ số, lưu HMAC trong Redis (hiệu lực 5 phút), gửi email.
  3. Khách nhập mã (POST /auth/verify). Mã đúng thì tài khoản isActive = true.
  4. Khách đăng nhập (POST /auth/login) và nhận access token cùng cookie refresh token.

Luồng thay thế​

LuồngMô tả
Đăng nhập GooglePOST /auth/google/login với ID token; hệ thống xác minh với GOOGLE_CLIENT_ID, yêu cầu email_verified, tạo hoặc đăng nhập tài khoản google. Mật khẩu đặt sau bằng set-password
Gửi lại mãPOST /auth/resend-code, chờ 60 giây giữa hai lần
Quên mật khẩuPOST /auth/forgot-password gửi link; POST /auth/reset-password với token và mật khẩu mới (tối thiểu 6 ký tự)
Đổi mật khẩuPOST /auth/change-password khi đã đăng nhập, cần mật khẩu hiện tại
Làm mới phiênrefresh-token

Luồng lỗi​

Tình huốngKết quả
Mã OTP sai400 kèm số lần còn lại; từ lần sai thứ 5, 403
OTP hết hạn400 "Mã xác thực đã hết hạn hoặc không tồn tại"
Không xác thực trong 15 phútTài khoản bị MongoDB TTL xóa
Chưa kích hoạt khi đăng nhập400
Tài khoản bị khóa, xóa, hoặc vô hiệu401
Đang chờ xóa403
Vượt giới hạn tốc độ429

Quy tắc nghiệp vụ​

  • Tối đa 5 phiên đồng thời; vượt thì phiên dùng lâu nhất bị xóa.
  • Chính sách mật khẩu không nhất quán (đăng ký chỉ cần không rỗng): auth endpoints.
  • Không có xác thực hai yếu tố trong source.

Edge case​

  • Gửi OTP đến email đã có tài khoản chưa kích hoạt: resend-code từ chối nếu tài khoản đã kích hoạt ("Tài khoản đã được kích hoạt rồi").
  • Link đặt lại mật khẩu mất hiệu lực khi backend khởi động lại (auth-and-sessions).
  • Hai lần làm mới token đồng thời làm một lần thất bại.

Sơ đồ liên quan​

refresh-token, mô-đun auth-and-sessions.