
DINHDANH Creator · Bài F03 · Nâng cao
login.json & ba vai trò user / admin / superadmin
Bài này giải thích vì sao bạn không tự viết hệ thống đăng nhập riêng - và cách dùng đúng các hàm auth có sẵn của Aura.
Mục tiêu bài học: Hiểu 3 vai trò admin, biết login.json là gì và vì sao không được đọc/ghi trực tiếp, và cách bảo AI viết đúng trang admin.
Thời lượng đọc: khoảng 12 phút
Điều kiện trước: Đã xem tab Backend (F01).
Bài trước → sau: F01 → F03 → G01 (Aura CMS dùng chung hệ superadmin)
1. Sơ đồ luồng đăng nhập admin
2. Thuật ngữ (bảng 3 cột)
| Thuật ngữ | Nghĩa | Nơi thấy trên UI |
|---|---|---|
| login.json | File hệ thống duy nhất chứa danh sách admin - không đọc/ghi trực tiếp được | Ẩn - quản lý qua đăng nhập / Admin Management |
| Guest | Khách chưa đăng nhập - chỉ gửi form công khai (appendData) | Trang công khai |
| user (Biên tập viên) | Nhân viên nhập/sửa nội dung CMS - không quản lý tài khoản hay cấu hình bảo mật | CMS → vai trò Biên tập viên (G05) |
| admin (Quản trị viên) | Quản lý shop/đơn hàng, sửa cấu hình site - không thêm/xóa superadmin | CMS → Quản trị viên |
| superadmin | Toàn quyền: thêm tài khoản, bảo mật, MCP - thường 1-2 người | Bootstrap lần đầu / CMS Superadmin |
| Bootstrap | Giai đoạn chưa có admin - người đầu tiên đăng ký tự thành superadmin | Form "Lần đầu thiết lập" (G01) |
3. Ba vai trò - giải thích bằng ví von
Hãy hình dung app như một cửa hàng:
- Guest = khách vào cửa, chỉ được để lại phiếu liên hệ (form).
- user (Biên tập viên) = nhân viên kho - nhập bài, sửa sản phẩm, không được mở két sắt.
- admin (Quản trị viên) = quản lý ca - xử lý đơn, đổi cài đặt shop, không thuê/sa thải chủ.
- superadmin = chủ cửa hàng - thêm tài khoản, bật bảo mật, cấu hình MCP.
Chỉ có đúng 3 role hợp lệ: user, admin, superadmin - không có editor/viewer/moderator. Cần phân quyền chi tiết hơn → ẩn/hiện nút trên trang, nhưng backend vẫn chặn nếu role không đủ.
4. Ma trận quyền theo vai trò

| Hành động | Guest | user | admin | superadmin |
|---|---|---|---|---|
| appendData (form public) | ✅ | - | - | - |
| appendData / updateData nội dung CMS | ❌ | ✅** | ✅ | ✅ |
| writeFile / writeField dữ liệu thường | ❌ | ✅ | ✅ | ✅ |
| writeFile file hệ thống (cms-settings.json) | ❌ | ❌ | ✅ | ✅ |
| listAdmins / updateAdmin / deleteAdmin / hardDeleteFile | ❌ | ❌ | ❌ | ✅ |
** user vẫn cần đăng nhập, chỉ bị giới hạn ở vài tác vụ quản trị cấp cao.
4. Các bước dựng trang admin qua AI
- Yêu cầu AI: "Tạo trang login.html cho admin, gọi registerAdmin khi chưa có ai (bootstrap), sau đó dùng login() để đăng nhập".
- Yêu cầu AI thêm vào đầu mọi trang quản trị: kiểm tra còn đăng nhập admin; nếu không hợp lệ thì chuyển hướng về login.html.
- Nếu cần nhiều người quản lý, tạo trang riêng chỉ superadmin thấy: "ẩn nút quản lý tài khoản nếu role khác superadmin, nhưng vẫn để backend tự chặn - không cố bỏ qua chặn bảo mật bằng cách nhờ AI vô hiệu hóa kiểm tra phía máy chủ".
- Kiểm tra lại trong tab Backend → Admin Management: xem số admin đã đăng ký, số phiên đang hoạt động; dữ liệu nhạy cảm (mật khẩu đã mã hóa phía hệ thống, phiên đăng nhập) luôn bị ẩn ở đây.
5. So sánh với công cụ khác
- Firebase Auth / Auth0: cũng tách riêng dịch vụ auth khỏi code app, nhưng phải tích hợp SDK phức tạp hơn; Aura chỉ cần vài hàm appifio_client có sẵn.
- WordPress: có sẵn hệ role (admin, editor, author…) chi tiết hơn; Aura đơn giản hoá về 3 vai trò cho web tự dựng.
- Tự viết PHP/Node auth: Aura tránh cho bạn việc tự mã hóa mật khẩu, tự cấp phiên đăng nhập, tự chống rate-limit - toàn bộ đã có sẵn.
6. Giới hạn kỹ thuật
Làm được
- 3 vai trò + bootstrap superadmin
- Đăng nhập CMS và trang admin app dùng chung login.json
- Đổi mật khẩu, thêm admin qua API có sẵn
Không làm được
- Không tạo role tùy ý (editor, viewer…)
- Không đọc/ghi login.json trực tiếp
- Không xóa superadmin cuối cùng
- Không tự viết file users.json riêng - hệ thống không nhận
7. Bảo mật - nguyên tắc bắt buộc
Không tự tạo file auth riêng (auth.json, users.json, admins.json…) - hệ thống sẽ không nhận diện, người dùng không login được vào trang admin tự viết đó.
Không đọc/ghi login.json trực tiếp - gọi sẽ bị chặn 403. Luôn dùng registerAdmin / login / logout / getSession / getAuthSetupStatus / changePassword / updateProfile.
- listAdmins/getSession không bao giờ trả mật khẩu gốc hay phiên đăng nhập dạng lộ - không lo AI "vô tình" hiển thị mật khẩu ra trang.
- Đổi mật khẩu người khác qua updateAdmin sẽ tự invalidate toàn bộ session cũ của họ.
- Không thể xóa hoặc hạ quyền superadmin cuối cùng - tránh tình trạng app mất hết quyền quản trị.
- Đăng nhập sai nhiều lần liên tục sẽ bị rate limit tạm thời (không phải lỗi hệ thống).
7. Vấn đề thường gặp
| Tình huống | Xử lý |
|---|---|
| AI tạo file users.json riêng, login không được | Yêu cầu AI xóa file đó, chuyển toàn bộ sang registerAdmin/login đúng chuẩn |
| Không tạo được superadmin thứ 2 | Đúng - từ người thứ 2, chỉ superadmin hiện tại mới gọi được registerAdmin |
| Muốn dùng role "editor" | Không hỗ trợ - chỉ 3 role user/admin/superadmin; dùng logic ẩn/hiện tính năng riêng nếu cần phân quyền chi tiết hơn |
| Đăng nhập báo "IP blocked" | Sai mật khẩu quá nhiều lần liên tiếp - đợi rồi thử lại, không spam submit |
8. Lời khuyên
- Bootstrap tài khoản superadmin đầu tiên ngay khi vừa dựng xong khung app - đừng để trang admin "mở public" quá lâu.
- Với team nhiều người, cấp role
admincho nhân viên thường, chỉ giữsuperadmincho 1-2 người quản lý cấp cao. - Luôn thử đăng xuất/đăng nhập lại sau khi đổi mật khẩu để chắc chắn session cũ đã bị hủy đúng.
9. Checklist tự kiểm
- Bạn nêu được 3 role hợp lệ và sự khác nhau cơ bản?
- Bạn hiểu vì sao không được tự tạo file auth riêng?
- Bạn biết kiểm tra còn đăng nhập admin dùng để làm gì và đặt ở đâu trong trang?
Bài tiếp theo
F04 - Secrets manager & Backend Function
Khi cần gọi API bên thứ 3 (gửi mail, thanh toán) mà không để lộ key, bạn sẽ dùng Secrets manager kết hợp executeBackendFunction.
Điều hướng nội bộ (cùng ngôn ngữ)
DINHDANH Creator · Bộ hướng dẫn người dùng · F03 · Đăng nhập quản trị & vai trò