AUTHORIZATION MANAGEMENT
Vì sao cần phân quyền?
Authorization không chỉ kiểm tra user đã đăng nhập. Hệ thống còn phải biết user được làm gì và có được chạm vào tài nguyên cụ thể đó hay không.
Một request đi qua
5 lớp kiểm traLuồng tổng quát
Gateway xác minh JWT bằng JWKS, loại identity header giả và tạo user context đáng tin cậy.
Permissions Guard so grant của user với quyền mà route yêu cầu; thiếu quyền thì dừng tại Gateway.
Auth Service hợp nhất role, assignment, permission và scope đang active thành access profile.
Domain service kiểm tra ownership và scope trên shop, product hoặc resource cụ thể trước mutation.
Request hợp lệ được forward; UI dùng access profile để hiện đúng navigation, còn request sai nhận 401 hoặc 403.
Điểm kiểm soát: frontend chỉ trình bày khả năng; quyết định bảo mật luôn nằm ở Gateway và service sở hữu resource.
Đi từ nơi policy được resolve đến cách quyền được enforce, cache và truy vết.
Request path · sáu chặng
Frontend gửi tín hiệu, backend mới ra quyết định
Client
Làm gì?
Browser gửi Bearer token kèm endpoint, action và dữ liệu cần xử lý. Identity header do client tự gắn chỉ là thông tin tham khảo.
Tại sao?
Mọi dữ liệu từ browser đều có thể bị sửa. Nếu tin userId, role hoặc permission do client gửi, người dùng có thể tự nhận danh tính và quyền cao hơn.
Identity
Làm gì?
Gateway đọc Bearer token. JWKS (JSON Web Key Set) là endpoint công khai các public key mà hệ thống phát hành token dùng để ký JWT; Gateway lấy đúng key để kiểm tra chữ ký, issuer, audience và thời hạn rồi tạo trusted user context.
Tại sao?
JWKS giúp Gateway xác minh token mà không cần biết private key. Khi auth service đổi key, danh sách public key được cập nhật để việc xác minh vẫn an toàn; các service phía sau chỉ nhận danh tính đã kiểm tra.
Route
Làm gì?
Permissions Guard đọc permission metadata của route rồi đối chiếu với grant có trong access profile của user. Thiếu grant thì dừng request và trả 403.
Tại sao?
JWT chỉ chứng minh user là ai; nó không tự chứng minh user được gọi endpoint nào. Vì vậy đăng nhập thành công vẫn có thể bị chặn ở lớp route.
Proxy
Làm gì?
Gateway loại bỏ identity header do browser gửi, sau đó chuyển request cùng trusted user context tới service sở hữu dữ liệu.
Tại sao?
Service phía sau chỉ nhận một contract identity thống nhất: user đã xác minh, grant đã kiểm tra và thông tin request cần thiết.
Resource
Làm gì?
Domain service lấy resource thật rồi kiểm tra actor có đúng shop, product hoặc resource hay không; đồng thời xác nhận action nằm trong scope trước khi mutation.
Tại sao?
Permission route chỉ cho phép gọi đúng loại endpoint, không cấp quyền lên mọi dữ liệu. User có thể được apply nhưng vẫn không được sửa sản phẩm thuộc shop khác.
Decision
Làm gì?
Hệ thống tổng hợp kết quả của identity, route grant và resource scope. Chỉ khi cả ba hợp lệ request mới vào handler nghiệp vụ; nếu không, request kết thúc tại lớp kiểm tra tương ứng.
Tại sao?
UI và backend cần phân biệt đúng nguyên nhân: 401 là chưa xác thực được token, còn 403 là đã biết user nhưng user không đủ quyền hoặc không thuộc phạm vi resource.
Admin
Làm gì?
Admin đọc danh sách role, permission, assignment và scope đang áp dụng cho từng shop hoặc resource.
Tại sao?
Phải biết policy hiện tại trước khi sửa để tránh cấp nhầm quyền, tạo grant trùng hoặc ảnh hưởng ngoài phạm vi quản lý.
Command
Làm gì?
Admin gửi PATCH với grant mới cùng actor context đã xác thực; backend kiểm tra payload và quyền quản trị trước khi ghi.
Tại sao?
Thay đổi policy là một mutation nhạy cảm, nên không thể chỉ dựa vào userId do client gửi hoặc cho mọi user gọi trực tiếp.
Trace
Làm gì?
Sau khi ghi policy, hệ thống lưu actor, before/after change và thời điểm; đồng thời tăng permissionVersion và loại access profile cũ khỏi cache.
Tại sao?
Nếu cache quyền cũ còn tồn tại, request sau đó có thể dùng grant đã bị thu hồi; audit cũng cần đủ dữ liệu để truy lại ai đã đổi gì.
Runtime
Làm gì?
Request tiếp theo resolve lại access profile từ role, assignment, scope và permissionVersion mới; frontend dùng profile đó để cập nhật navigation.
Tại sao?
Quyền vừa đổi chỉ nên xuất hiện sau khi runtime lấy được profile mới, tránh UI hiển thị quyền mà API chưa chấp nhận hoặc ngược lại.
Next.jsAdmin UI
NestJSAuth API
PostgreSQLPolicy & user data
RedisAccess cache
KeycloakToken issuer · RS256
JWTAccess token · RS256JwtAuthGuard xác minh JWT bằng public key từ Keycloak JWKS; PermissionsGuard đọc @RequirePermissions và trả 401/403 trước khi proxy.
Phát hành access token theo realm bin-ecommerce và công bố JWKS endpoint để Gateway kiểm tra chữ ký RS256.
Nhận context đã xác thực, rồi tự kiểm tra shop, owner, resource và scope trước khi thực hiện mutation.
Đọc overview, nhận PATCH role-permission, resolve access profile và ghi audit change.
Lưu user, role, permission, assignment, scope, navigation và permission audit log.
Cache access profile theo userId và permissionVersion; cache chỉ tăng tốc, không thay nguồn policy.
Gọi profile đã lọc để dựng navigation, default route và màn hình access denied; không tự quyết định quyền.
Ranh giới service: Keycloak phát hành token; API Gateway xác minh và enforce route; Auth Service quản lý policy/profile; domain service enforce resource; web chỉ trình bày kết quả.
Nó là gì?
Permission là quyền cho phép một user thực hiện một action cụ thể trên một endpoint, ví dụ xem, tạo, apply hoặc rollback.
Giải quyết bài toán gì?
Đăng nhập chỉ cho biết user là ai, không có nghĩa user được gọi mọi API. Lớp này ngăn request thiếu quyền đi sâu vào service và tránh frontend tự thêm role/permission để nâng quyền.
Route khai báo action cần có
Decorator @RequirePermissions gắn permission metadata vào endpoint. Ví dụ image optimization tách riêng view, generate, apply và rollback.
PermissionsGuard đối chiếu grant
Guard đọc trusted context do JwtAuthGuard tạo, lấy access profile của user và tìm grant có code/action khớp route. Permission không lấy từ body hoặc header do browser tự gửi.
Chỉ request hợp lệ mới được forward
Đủ grant thì Gateway chuyển request cùng context xuống proxy; thiếu grant thì dừng ngay tại Gateway, không để business handler phía sau chạy.
Nó là gì?
Ownership và scope là giới hạn dữ liệu mà một permission được phép tác động tới: của chính user, của shop, shop được phân công hoặc toàn hệ thống.
Giải quyết bài toán gì?
Một user có thể có permission đúng nhưng vẫn không được sửa resource của shop khác. Domain service cần kiểm tra resource thật để ngăn truy cập chéo dữ liệu.
Permission trả lời “được làm gì?”
Ví dụ SELLER_PRODUCT_UPDATE chỉ nói user được gọi hành động cập nhật product. Nó chưa nói product đó thuộc shop nào.
Scope trả lời “được làm ở đâu?”
Domain service phải lấy resource thật và đối chiếu owner/shop/assignment với actor context trước khi đọc hoặc ghi dữ liệu. Vì vậy UI ẩn nút không thay thế được kiểm tra backend.
Cách đọc: permission xác định action như product.update; scope giới hạn resource mà action đó được phép tác động. Domain service luôn lấy actor từ trusted context và lấy owner/shop từ database, không dùng ownerId hoặc shopId do client tự khai báo.
| Scope | Ý nghĩa nghiệp vụ | Domain lấy và đối chiếu | Ví dụ trong hệ thống | Kết quả khi không đạt |
|---|---|---|---|---|
| global | Action được phép trên phạm vi toàn hệ thống, không bị giới hạn bởi owner hoặc shop. | Gateway/domain vẫn phải thấy đúng permission global; không được suy ra global chỉ vì user có role admin. | Tác vụ quản trị policy hoặc dữ liệu dùng chung. | 403 nếu action không có grant global tương ứng. |
| own | User chỉ được thao tác bản ghi mà chính user đó sở hữu. | Domain lấy ownerId của resource từ database và so với actorId trong trusted context; ownerId trong body không có giá trị quyết định. | Đọc hoặc sửa bản ghi thuộc user hiện tại. | Trả 403 trước khi đọc tiếp hoặc thực hiện mutation. |
| own_shop | Seller được thao tác resource thuộc shop mà seller sở hữu/quản lý. | Domain lấy shopId của product/resource thật, sau đó đối chiếu với shop membership/ownership đã resolve từ actor. | Seller cập nhật product trong shop của mình. | Trả 403 và không chạy câu lệnh UPDATE lên resource shop khác. |
| assigned_shop | Staff chỉ được thao tác các shop được phân công trong thời gian còn hiệu lực. | Domain kiểm tra assignment đúng actor, đúng shop, chưa revoked/inactive và chưa hết hạn. | Staff xử lý dữ liệu của shop được phân công. | Trả 403; không tin shopId từ body để chuyển sang shop khác. |
Thứ tự bảo vệ: Gateway kiểm tra route permission trước; domain service kiểm tra ownership và scope sau. Chỉ khi cả hai lớp hợp lệ, business logic mới được phép chạy.
Nó là gì?
Policy command là request dùng để cấp, gỡ hoặc thay đổi role, permission, assignment và scope trong hệ thống.
Giải quyết bài toán gì?
Đây là thao tác có thể làm thay đổi quyền của nhiều user. Nếu không xác thực actor, payload và phạm vi, admin giả hoặc client có thể tự cấp quyền vượt giới hạn.
Bước 1 · Actor
Actor lấy từ JWT context đã verify, không lấy userId do client gửi trong body. Gateway kiểm tra grant quản trị rồi mới chuyển request tới auth-service.
Bước 2 · Payload
PATCH mô tả role, permission, assignment hoặc scope cần cấp/gỡ. DTO validation loại field sai, thiếu field bắt buộc và dữ liệu ngoài contract.
Bước 3 · Policy check
Auth Service xác minh admin có được sửa policy của shop/resource đó không, tránh cấp quyền vượt quá phạm vi quản trị.
Bước 4 · Commit
Chỉ khi các kiểm tra đều đạt, auth-service mới commit policy. Lỗi validation, thiếu quyền hoặc sai scope dừng trước mutation.
Nó là gì?
Audit là nhật ký thay đổi quyền; invalidate là loại access profile cũ khỏi Redis sau khi policy đã thay đổi.
Giải quyết bài toán gì?
Nếu chỉ cập nhật database mà giữ cache cũ, user có thể tiếp tục dùng quyền đã bị thu hồi. Nếu không có audit, hệ thống không trả lời được ai đã cấp/gỡ quyền và thay đổi lúc nào.
Bước 1 · Change
Commit policy mới
Role/permission change hợp lệ được ghi vào PostgreSQL, nguồn dữ liệu chuẩn của policy. Bản ghi chỉ được tạo sau khi actor, payload và phạm vi đã qua kiểm tra.
Bước 2 · Audit
Lưu before/after
Auth Service ghi actorUserId, nội dung trước/sau, thời điểm và request context để trả lời ai đã đổi gì, đổi lúc nào và đổi trong phạm vi nào.
Bước 3 · Version
Đánh dấu profile cũ
permissionVersion tăng sau thay đổi. Profile đang mang version cũ được xem là stale, không còn đại diện cho policy hiện tại.
Bước 4 · Invalidate
Buộc resolve lại
Redis bị invalidate; lần /me hoặc /refresh sau phải tạo access profile mới. Quyền vừa bị gỡ không thể tiếp tục sống vô thời hạn trong cache.
Ranh giới dữ liệu: PostgreSQL giữ policy và audit; Redis chỉ giữ bản sao access profile để đọc nhanh. Dù cache có lỗi, JwtAuthGuard, PermissionsGuard và domain ownership check vẫn không bị bỏ qua.
Nó là gì?
Access profile là “bảng quyền hiện tại” đã được Auth Service tổng hợp cho một user: user là ai, được làm action nào, trên phạm vi nào và thấy khu vực nào trên web.
Giải quyết bài toán gì?
Role, assignment, permission và scope nằm ở nhiều nguồn. Nếu mỗi service tự đọc và tự hiểu khác nhau, UI có thể hiển thị sai quyền hoặc request dùng policy không đồng nhất.
Bước 1 · Identity
Xác định user
Gateway đã xác minh JWT nên Auth Service biết request thuộc user nào. Hệ thống lấy role trong token để tương thích và lấy thêm user-role assignment trong database, nhưng chỉ giữ assignment còn active, chưa revoked và chưa hết hạn.
Bước 2 · Policy
Đọc luật quyền
Auth Service đọc role-permission, grant, scope, area access, navigation và permissionVersion từ PostgreSQL. Đây là policy server-side; user không thể gửi body để tự thêm role hoặc permission.
Bước 3 · Kết quả
Bảng quyền hiện tại của user
Auth Service lọc role không còn hiệu lực rồi merge grant và scope thành access profile. Profile này trả lời được user có action nào, trên phạm vi nào và được hiển thị khu vực nào trong web.
Bổ sung · Cache
Khi nào dùng cache?
Profile được cache theo userId + permissionVersion để không phải join lại role/permission ở mọi lần đọc. Cache chỉ là bản sao tăng tốc; khi version đổi hoặc cache bị invalidate, hệ thống phải đọc policy và tạo profile mới.
Bổ sung · Ví dụ
Khi admin gỡ quyền
Auth Service tăng version và xóa profile cũ; lần /me hoặc /refresh sau không còn grant update, web ẩn nút sửa, nhưng Gateway/domain vẫn kiểm tra quyền độc lập khi seller gọi API.
