Đă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
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/usersbằ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ốiauthđã 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ó tronguser.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.tsxbị bỏ qua vàcheckbáoconfig.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.
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
401mãUNAUTHENTICATED; sai vai nhận403mã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ỗi400lộ cấu trúc dữ liệu. - Vai lạ bị
checkbáoaccess.unknown-role. API ghi dữ liệu mà để"public"bị cảnh báoaccess.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ả429mãRATE_LIMITED. Đổi mức bằngexport const rateLimit = { max: 5, windowSec: 600 }, tắt bằngexport 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
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 quauseApiClient()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ùnggetUser().- Trang
/login,/registercủa khốiauthtự hiện nút Google. Ở trang bạn tự viết, gọiawait 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/oauthhay 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 headerAuthorizationchạ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
accesshaymiddleware.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ì
checkcảnh báoabuse.password-external.
Bước tiếp theo
- Trang đăng nhập và đăng ký — dựng trang đăng nhập, chặn trang khi chưa đăng nhập.
- auth.ts — mọi khoá, bảng
usersvà các API sinh sẵn. - AI và kho file — gọi AI và lưu file từ handler.