Skip to Content

Đăng nhập và phân quyền

Khoảng 15 phút. Làm xong, app của bạn có đăng nhập, có vai trò (ví dụ nhân viên, quản lý, admin) và mỗi API chỉ mở cho vai trò được phép.

Bạn không viết code đăng nhập, chỉ khai báo vai trò và cách đăng ký trong app/auth.ts. Lúc build, manh.run sinh bảng users, API đăng nhập và API quản lý người dùng. Token là JWT gửi trong header Authorization, ký bằng JWT_SECRET riêng của app.

Khai báo app/auth.ts

app/auth.ts
export default { roles: ["admin", "manager", "staff"], defaultRole: "staff", signup: "closed", providers: ["google"], labels: { manager: "Quản lý cửa hàng" }, };
  • Vai trò đầu tiên quản lý người dùng. Vai này thuộc về tài khoản đầu tiên đăng ký trong bản xem trước ở không gian làm việc của chủ app, khi app chưa có ai giữ vai đó. Trên app chạy thật, người đăng ký luôn nhận defaultRole, nên người lạ không chiếm được quyền quản trị bằng cách đăng ký trước.
  • signup: "open" thì ai cũng đăng ký được. "closed" thì chỉ admin đầu tiên tự đăng ký; nhân viên được thêm ở trang /users bằng nút Thêm tài khoản (tên, email, mật khẩu đầu, vai trò).
  • providers: ["google"] bật nút đăng nhập bằng Google. Khối auth đã ghi sẵn dòng này. manh.run dùng ứng dụng Google của chính mình, nên bạn không phải đăng ký gì và app không giữ khoá nào. Tài khoản Google và tài khoản mật khẩu trùng email là cùng một người.
  • labels đặt tên vai hiện trên màn hình. Vai thông dụng (admin, owner, manager, staff, technician, cashier…) đã có sẵn tên tiếng Việt.
  • profile: { branchId: "int" } thêm cột vào bảng người dùng; giá trị có trong user.branchId ở mọi handler.
  • File chỉ chứa giá trị viết thẳng, đuôi .ts, vì manh.run đọc file chứ không chạy nó. app/auth.tsx bị bỏ qua và check báo config.wrong-extension.

manh.run sinh các API api.auth.login, api.auth.register, api.auth.me, api.users.list, api.users.create, api.users.update và api.users.members() (danh sách người đang hoạt động cho ô chọn người, ai đăng nhập cũng gọi được). Muốn sửa một phần, viết file của bạn đúng đường dẫn của file sinh sẵn; manh.run dùng file trong project.

POST /auth/login tự chặn sau 5 lần sai mật khẩu với một email, hoặc 30 lần sai từ một địa chỉ IP, trong 15 phút: trả 429 mã TOO_MANY_ATTEMPTS kèm header Retry-After. Đăng nhập đúng thì xoá bộ đếm. Màn đăng nhập hiện message của lỗi là đủ.

Ai được gọi API

Mỗi handler export access. Không khai báo thì handler chỉ cho người đã đăng nhập gọi.

app/orders/[id:int]/status/post.ts
import { z } from "@hono/zod-openapi"; import { moveOrder } from "../../repository"; export const access = ["manager", "admin"]; export const schema = { body: z.object({ to: z.enum(["confirmed", "done"]) }) }; export default (c, { user, param, body }) => moveOrder(user, param.id, body.to);
  • "public": ai cũng gọi được. "user": ai đã đăng nhập. ["manager", "admin"]: chỉ các vai này.
  • Chưa đăng nhập nhận 401 mã UNAUTHENTICATED; sai vai nhận 403 mã FORBIDDEN. Quyền được kiểm trước dữ liệu gửi lên, nên người sai vai không bao giờ thấy lỗi 400 lộ cấu trúc dữ liệu.
  • Vai lạ bị check báo access.unknown-role. API ghi dữ liệu mà để "public" bị cảnh báo access.public-write; với form liên hệ hay đặt lịch công khai thì vẫn được.
  • API ghi để "public" tự giới hạn 30 lần mỗi 10 phút cho mỗi IP và mỗi route, quá thì trả 429 mã RATE_LIMITED. Đổi mức bằng export const rateLimit = { max: 5, windowSec: 600 }, tắt bằng export const rateLimit = false (webhook từ hệ thống khác).
  • Lọc dữ liệu theo người dùng (đơn của chính người tạo) vẫn viết trong repository: where(eq(orders.createdBy, user.id)).

Áp cho cả thư mục: đặt export const access = ["admin"]; trong middleware.ts của thư mục đó, ví dụ app/(admin)/middleware.ts. Handler nào tự khai báo access thì dùng giá trị của handler.

Phiên đăng nhập ở giao diện

app/login/page.tsx
import { LoginForm, ProFormText } from "@ant-design/pro-components"; import { useNavigate } from "react-router-dom"; import { useApiClient } from "app/api"; import { signIn } from "app/hooks"; export default function LoginPage() { const api = useApiClient(); const nav = useNavigate(); return ( <LoginForm title="Đăng nhập" onFinish={async (values) => { signIn(await api.auth.login(values)); nav("/"); return true; }}> <ProFormText name="email" placeholder="Email" rules={[{ required: true }]} /> <ProFormText.Password name="password" placeholder="Mật khẩu" rules={[{ required: true }]} /> </LoginForm> ); }
  • signIn(...) lưu token; từ đó mọi lời gọi qua useApiClient() tự gửi token. signOut() đăng xuất.
  • const { user, hasRole } = useSession() cho biết ai đang đăng nhập và vẽ lại giao diện khi đăng nhập, đăng xuất. Ngoài React dùng getUser().
  • Trang /login, /register của khối auth tự hiện nút Google. Ở trang bạn tự viết, gọi await signInWith("google") từ app/hooks.

Thử từng vai trò

Muốn thử màn của quản lý hay admin trước khi chủ app đăng ký, nhờ agent gọi tool create_test_accounts. Tool này tạo một tài khoản cho mỗi vai trên app đã deploy (<vai>@test.manh.invalid, mật khẩu mới mỗi lần gọi). Xoá chúng bằng remove_test_accounts trước khi bàn giao. Đừng nâng quyền tài khoản bằng SQL.

Cần biết

  • Không dùng manh/oauth hay session bằng cookie. Module đó không có, và bản chạy thử trong bảng điều khiển gọi API từ một origin khác nên cookie không đi theo. Token trong header Authorization chạy ở cả hai nơi.
  • Ẩn nút trên giao diện chỉ để đỡ bấm nhầm. Server kiểm vai qua access ở mọi handler ghi dữ liệu.
  • Cron, email đến và tin Telegram không đi qua access hay middleware.ts, và không có người dùng trong request.
  • Không bao giờ trả passwordHash, kể cả ở API bạn tự viết.
  • Trang có ô mật khẩu chỉ gửi mật khẩu về API của chính app. Gửi ra địa chỉ ngoài thì check cảnh báo abuse.password-external.

Bước tiếp theo

Cập nhật