Authentication Specification
Tài liệu đặc tả yêu cầu và kiến trúc xác thực cho EduOne AI Platform
1. Document Purpose
Click to view detailed specifications & content
Tài liệu này mô tả các yêu cầu đối với hệ thống Authentication (xác thực) của EduOne AI Platform.
Authentication chịu trách nhiệm:
- Xác thực người dùng (Who are you?).
- Quản lý phiên đăng nhập (Session management).
- Xác định danh tính (Identity mapping).
- Cung cấp Token/Identity cho toàn bộ hệ thống.
Authentication không chịu trách nhiệm:
- Authorization (Phân quyền hành động).
- RBAC (Role-Based Access Control).
- Business Permission (Quyền nghiệp vụ).
- Recommendation (Đề xuất hoạt động).
- User Profile (Thông tin chi tiết hồ sơ).
2. Design Principles
Click to view detailed specifications & content
Hệ thống xác thực được thiết kế theo các nguyên tắc cốt lõi:
- AP-01 — Passwordless (Không mật khẩu): Hệ thống không quản lý, không lưu trữ mật khẩu của người dùng, loại bỏ hoàn toàn các rủi ro lộ lọt mật khẩu.
- AP-02 — Identity Delegation (Ủy thác danh tính): Việc xác thực danh tính được giao hoàn toàn cho Google thông qua cơ chế Google OAuth. EduOne không tự thực hiện đăng ký tài khoản mới.
- AP-03 — Cloudflare Native (Tối ưu hóa Cloudflare): Sử dụng tối đa hạ tầng Cloudflare Stack để thực hiện xác thực tại Edge, giảm thiểu tối đa độ trễ.
- AP-04 — Zero Trust (Không tin tưởng mặc định): Mọi request từ phía client gửi lên API Gateway bắt buộc phải được xác thực danh tính rõ ràng.
- AP-05 — Least Privilege (Đặc quyền tối thiểu): Tầng Authentication chỉ xác thực danh tính (Identity), không tự ý quyết định quyền hạn nghiệp vụ của người dùng.
3. Product Scope
Click to view detailed specifications & content
Hệ thống xác thực trong phiên bản Prototype/MVP chỉ hỗ trợ duy nhất:
- Google Account (Google Sign-In)
Các phương thức xác thực không hỗ trợ (nằm ngoài phạm vi):
- Email + Password truyền thống.
- Facebook Login, GitHub Login, Microsoft Login, Apple Login.
- Đăng nhập qua số điện thoại / SMS OTP.
- Magic Link (đăng nhập qua liên kết email).
- Anonymous Login (đăng nhập ẩn danh).
4. Authentication Architecture
Click to view detailed specifications & content
Sơ đồ kiến trúc xác thực tại Edge mạng lưới Cloudflare:
text
Browser (Client UI)
│
▼
Cloudflare Pages (Frontend Hosting)
│
▼ (Redirect / Check Session)
Cloudflare Access (Identity Provider / Gateway)
│
▼ (Verify Credential)
Google OAuth ➔ Google Identity Service
│
▼ (Issue Identity JWT)
Cloudflare Access
│
▼ (Inject JWT in Header)
Cloudflare API Gateway
│
▼ (Validate JWT Signature & Claims)
Cloudflare Workers (Backend APIs)Cloudflare Access đóng vai trò là Identity Provider trung gian, tích hợp trực tiếp với Google OAuth để cấp phát JWT cho client.
5. Login Flow
Click to view detailed specifications & content
Luồng đăng nhập chi tiết của người dùng:
text
User (Chưa đăng nhập)
│
▼
Bấm nút "Login with Google" trên Client UI
│
▼
Client chuyển hướng tới Google OAuth Consent Page
│
▼
Người dùng chọn tài khoản Google & đồng ý cấp quyền
│
▼
Google redirect kết quả về Cloudflare Access callback
│
▼
Cloudflare Access xác minh token Google ➔ Tạo Session & JWT
│
▼
Client nhận JWT và lưu giữ an toàn dưới dạng HTTP-Only Cookie hoặc Header
│
▼
Các API calls tiếp theo đính kèm JWT này để gọi Backend6. Logout Flow
Click to view detailed specifications & content
Luồng đăng xuất của người dùng:
text
User (Đang đăng nhập)
│
▼
Bấm nút "Logout" trên giao diện
│
▼
Gửi request xóa session tới Cloudflare Access logout endpoint
│
▼
Cloudflare Access hủy bỏ session trên hệ thống
│
▼
Client xóa bỏ các cookies lưu trữ token xác thực
│
▼
Chuyển hướng người dùng về trang đăng nhập công cộng (Login Page)7. Supported Identity
Click to view detailed specifications & content
Mỗi thực thể định danh người dùng được liên kết với tài khoản Google chứa các thuộc tính:
- Google Subject ID (Mã định danh duy nhất của Google).
- Google Email (Địa chỉ email đăng ký).
- Display Name (Tên hiển thị mặc định).
- Avatar URL (Đường dẫn ảnh đại diện).
- Email Verified State (Trạng thái xác minh email của Google).
Hệ thống tuyệt đối không lưu trữ:
- Mật khẩu (Password).
- Lịch sử mật khẩu (Password History).
- Câu hỏi bảo mật phục hồi tài khoản (Recovery/Security Questions).
8. User Identifier
Click to view detailed specifications & content
Để đảm bảo tính độc lập và khả năng mở rộng trong tương lai:
- Mã định danh nội bộ (Internal User ID): Mỗi người dùng khi khởi tạo trên hệ thống sẽ được cấp một UUID ngẫu nhiên không trùng lặp, ví dụ:
usr_01HABX.... - Khóa chính cơ sở dữ liệu: ID nội bộ
usr_...này sẽ được sử dụng làm khóa chính (Primary Key) trong toàn bộ các bảng quan hệ của EduOne (D1 Database). - Quy tắc thiết kế: Không sử dụng Google Email hay Google Subject ID làm khóa chính để tránh phụ thuộc cứng vào nhà cung cấp Google, cho phép dễ dàng chuyển đổi sang Identity Provider khác sau này.
9. Authentication Token
Click to view detailed specifications & content
Cloudflare Access phát hành Token dưới dạng JSON Web Token (JWT).
Mỗi JWT hợp lệ chứa các claims thông tin tối thiểu:
- User ID (
sub) - Email (
email) - Issuer (
iss) - Expiration Time (
exp) - Session ID (
sid)
Quy tắc phân tách: JWT chỉ chứa thông tin định danh phục vụ xác thực (Authentication). Tuyệt đối không nhúng danh sách quyền hạn (Permissions), vai trò nghiệp vụ (Roles - ví dụ Student/Teacher) hay thông tin tiến trình học tập của học viên vào JWT để giữ token luôn nhỏ gọn.
10. Session Management
Click to view detailed specifications & content
Phiên đăng nhập (Session) được quản lý trực tiếp bởi Cloudflare Access.
Mỗi bản ghi Session bao gồm:
- Session ID (Định danh phiên duy nhất).
- Created Time (Thời điểm khởi tạo phiên).
- Expire Time (Thời điểm hết hạn phiên).
- Refresh Time (Thời điểm cần làm mới token).
- User Identity (Thông tin định danh liên kết).
11. Session Timeout
Click to view detailed specifications & content
Các tham số cấu hình thời gian hết hạn phiên đăng nhập trong bản thử nghiệm (Prototype):
- Idle Timeout (Thời gian chờ nhàn rỗi): 2 giờ. Nếu người dùng không thực hiện bất kỳ tương tác nào trong vòng 2 giờ, phiên sẽ tự động kết thúc.
- Maximum Session Lifespan (Tuổi thọ tối đa phiên): 24 giờ. Người dùng bắt buộc phải đăng nhập lại sau mỗi 24 giờ hoạt động liên tục.
- Remember Login (Duy trì đăng nhập): Có hỗ trợ để tăng trải nghiệm người dùng, duy trì trạng thái đăng nhập khi mở lại trình duyệt trong ngày.
12. API Authentication
Click to view detailed specifications & content
Tất cả các API nghiệp vụ của hệ thống được bảo vệ sau Cloudflare API Gateway:
- Kiểm tra JWT tại Edge: Mọi request gửi lên API bắt buộc phải đi qua API Gateway để kiểm tra chữ ký số (Signature) của JWT và xác thực thời hạn hiệu lực (
expclaim). - Xử lý phía backend: Cloudflare Workers ở backend chỉ tin tưởng các request đã được API Gateway xác thực thành công. Workers không trực tiếp gọi API của Google để kiểm chứng token, giảm thiểu đáng kể chi phí mạng và độ trễ.
13. Authentication Sequence
Click to view detailed specifications & content
Quy trình gửi request có xác thực:
text
Browser Cloudflare Access API Gateway Workers
│ │ │ │
├─ 1. Send API Req ──►│ │ │
│ (with JWT cookie) │ │ │
│ ├─ 2. Validate JWT ──►│ │
│ │ (Signature check) │ │
│ │ ├─ 3. Forward Req ─►│
│ │ │ (with User ID) │
│ │ │ ├─ 4. Run Business
│ │ │ │ Logic
│ │ │ ◄───┘
│ │ ◄─ 5. Return Res ───┤
◄─ 6. Return Data ────┼─────────────────────┘ │14. User Registration
Click to view detailed specifications & content
EduOne không hỗ trợ trang đăng ký tài khoản (Register Page). Việc tạo tài khoản mới diễn ra tự động (Just-In-Time Provisioning) trong lần đăng nhập đầu tiên:
- Người dùng thực hiện đăng nhập bằng Google thành công lần đầu.
- Hệ thống kiểm tra trong D1 Database xem Google Subject ID/Email đã tồn tại chưa.
- Nếu chưa tồn tại, hệ thống tự động tạo một bản ghi
Usermới với IDusr_...và gán vai trò mặc định (ví dụ: Student). - Khởi tạo bản ghi Learner Model trống cho học viên mới.
- Hiển thị màn hình chào mừng (Welcome Screen) để hướng dẫn người dùng bắt đầu.
15. User States
Click to view detailed specifications & content
Mỗi định danh người dùng trong hệ thống có thể chuyển trạng thái như sau:
INVITED(Được mời): Tài khoản được giáo viên hoặc admin khai báo trước nhưng chưa đăng nhập lần nào.ACTIVE(Đang hoạt động): Tài khoản đã đăng nhập thành công và được phép truy cập hệ thống.SUSPENDED(Tạm dừng): Tài khoản bị khóa tạm thời do vi phạm hoặc yêu cầu của giáo viên.DISABLED(Vô hiệu hóa): Tài khoản bị đóng vĩnh viễn.
Tầng Authentication chỉ quan tâm trạng thái là ACTIVE hay không. Nếu người dùng ở trạng thái SUSPENDED hoặc DISABLED, hệ thống sẽ từ chối truy cập ngay lập tức kể cả khi JWT của Google vẫn còn hiệu lực.
16. Account Linking
Click to view detailed specifications & content
Trong phiên bản Prototype/MVP:
- Không hỗ trợ liên kết nhiều tài khoản (Account Linking): Mỗi tài khoản người dùng nội bộ (
usr_...) chỉ được liên kết duy nhất với một tài khoản Google duy nhất. - Quy định: Không hỗ trợ việc gộp tài khoản hoặc liên kết thêm tài khoản thứ hai (như Facebook hay Microsoft) vào cùng một profile người dùng.
17. Authentication Events
Click to view detailed specifications & content
Mọi sự kiện liên quan đến xác thực bắt buộc phải được ghi nhật ký hệ thống (Audit Log) để phục vụ kiểm toán bảo mật:
LOGIN_SUCCESS: Đăng nhập thành công.LOGIN_FAILED: Đăng nhập thất bại (lỗi kết nối Google OAuth, lỗi từ chối cấp quyền).LOGOUT: Đăng xuất chủ động.SESSION_EXPIRED: Hết hạn phiên làm việc.TOKEN_INVALID: Token không hợp lệ (sai chữ ký số, bị thay đổi cấu trúc).TOKEN_EXPIRED: JWT hết hạn sử dụng.ACCOUNT_DISABLED: Cố gắng đăng nhập vào tài khoản đã bị khóa/vô hiệu hóa.
18. Security Requirements
Click to view detailed specifications & content
Quy chuẩn bảo mật bắt buộc đối với tầng xác thực:
- Không lưu trữ mật khẩu dưới bất kỳ dạng nào (kể cả dạng băm salt-hash).
- Không lưu trữ Google Access Token ở phía client (tránh rủi ro bị XSS đánh cắp quyền truy cập Google Drive/Gmail của người dùng).
- Toàn bộ lưu lượng truyền tải (traffic) bắt buộc phải sử dụng giao thức bảo mật HTTPS.
- Khóa bí mật (Secrets) dùng để ký số và giải mã JWT phải được lưu trữ và tiêm an toàn thông qua Cloudflare Secrets (không ghi cứng trong mã nguồn).
19. Cloudflare Services
Click to view detailed specifications & content
Các dịch vụ Cloudflare được sử dụng để xây dựng và bảo vệ tầng xác thực:
- Cloudflare Pages: Host ứng dụng Client.
- Cloudflare Access: Quản lý Identity Provider và tích hợp Google OAuth.
- Cloudflare API Gateway: Đóng vai trò kiểm tra tính hợp lệ của JWT ở Edge.
- Cloudflare Workers: Nhận diện và ánh xạ Identity sang các luồng nghiệp vụ.
- Cloudflare Secrets: Lưu trữ bảo mật các khóa cấu hình OAuth và JWT.
- Cloudflare WAF & Rate Limiting: Chống các cuộc tấn công Brute-Force hoặc spam request vào endpoint đăng nhập.
20. Error Handling
Click to view detailed specifications & content
Các mã lỗi trả về tương ứng khi gặp sự cố xác thực:
401 Unauthorized: Request không đính kèm JWT hoặc JWT không hợp lệ (sai signature, hết hạn). Hệ thống tự động chuyển hướng người dùng về màn hình đăng nhập.403 Forbidden: Xác thực thành công nhưng tài khoản đang ở trạng thái bị khóa (SUSPENDED/DISABLED).Expired Session: Hiển thị thông báo phiên làm việc hết hạn và chuyển hướng về Google Login.Google Login Failed: Hiển thị nút "Thử lại" trên màn hình login của EduOne.
21. Future Extensions
Click to view detailed specifications & content
Thiết kế hệ thống đảm bảo khả năng cắm rút dễ dàng trong tương lai để bổ sung:
- Microsoft Login (cho các trường học sử dụng Office 365).
- GitHub Login / Apple Login.
- Đăng nhập một lần (Enterprise SSO / SAML / OIDC) cho các tổ chức giáo dục quy mô lớn.
- Đăng nhập không cần tài khoản qua Magic Link.
Nhờ tách biệt tầng xác thực, việc bổ sung các nhà cung cấp dịch vụ này trong tương lai sẽ không yêu cầu bất kỳ thay đổi nào đối với code logic nghiệp vụ (Business Layer) phía sau.
22. Out of Scope
Click to view detailed specifications & content
Hệ thống không hỗ trợ và không phát triển các chức năng sau:
- Đổi mật khẩu (Change Password).
- Quên mật khẩu / Khôi phục mật khẩu (Forgot/Reset Password).
- Xác minh địa chỉ Email (Email Verification - vì Google đã xác minh sẵn).
- Đăng nhập bằng sinh trắc học (Biometric Authentication).
- Mã Captcha khi đăng nhập.
23. Acceptance Criteria
Click to view detailed specifications & content
Quy chuẩn nghiệm thu đối với tầng Authentication:
- [ ] Người dùng đăng nhập thành công bằng tài khoản Google.
- [ ] Cloudflare Access xác thực thành công và cấp phát JWT hợp lệ.
- [ ] Mọi API nghiệp vụ chỉ tiếp nhận và xử lý request chứa JWT hợp lệ.
- [ ] Cloudflare Workers không phải tự xử lý các thủ tục bắt tay OAuth trực tiếp.
- [ ] Tài khoản người dùng mới được tự động khởi tạo trong DB ở lần đăng nhập đầu tiên.
- [ ] Tài khoản bị đánh dấu
DISABLED/SUSPENDEDkhông thể gọi API thành công dù có JWT. - [ ] Toàn bộ API và giao diện web chạy 100% qua HTTPS.
- [ ] Không lưu trữ mật khẩu hoặc token Google trong database EduOne.
- [ ] Mọi sự kiện đăng nhập, đăng xuất và lỗi được lưu vào Audit Log.
24. Authentication vs Authorization Separation
Click to view detailed specifications & content
Kiến trúc EduOne tách biệt hoàn toàn 2 tầng xác thực và phân quyền để tối đa hóa khả năng bảo trì:
text
Who are you? (Identity)
┌─────────────────────────┐
│ AUTHENTICATION │
│ │
│ - Google OAuth │
│ - Cloudflare Access │
│ - Identity JWT │
└────────────┬────────────┘
│
▼ (Identity established)
What are you allowed to do? (Permissions)
┌─────────────────────────┐
│ AUTHORIZATION │
│ │
│ - D1 RBAC Roles │
│ - Business Policies │
│ - Override Rules │
└─────────────────────────┘- Authentication (Xác thực): Chịu trách nhiệm trả lời câu hỏi "Bạn là ai?". Tầng này xử lý ở biên Edge bởi Cloudflare Access và Google OAuth, trả về mã định danh người dùng duy nhất (
usr_...). - Authorization (Phân quyền): Chịu trách nhiệm trả lời câu hỏi "Bạn được phép làm gì?". Tầng này được xử lý hoàn toàn ở Application Layer (Workers) dựa trên cơ sở dữ liệu phân quyền RBAC lưu tại D1 Database (phân chia vai trò Student, Teacher, Author, Reviewer) và các logic chính sách nghiệp vụ.