Appearance
Mô hình Identity, Workspace và Access của MINAP
Version: 1.0
Date: 2026-11-12
Status: Working baseline
1. Quyết định cốt lõi
- Một người có một MINAP Account.
- Applications không tạo tài khoản nền tảng riêng cho cùng một người.
- Một MINAP Account có thể sở hữu Personal Workspace, tạo hoặc tham gia nhiều Organization Workspaces, và giữ vai trò khác nhau ở mỗi nơi.
- Mô hình phải hỗ trợ cả Personal + Organization từ MVP để tránh migration data-model phá vỡ trong tương lai.
- Keycloak là lựa chọn/định hướng identity tập trung. Hướng đăng nhập MVP: Email/Password và Google Login.
- ID entity nền tảng theo D-017: string
{prefix}_{nanoid}(ví dụ Accountacc_…, Workspacews_…); Keycloaksubchỉ là tham chiếu ngoài, không phải primary id công khai của MINAP Account.
2. Mô hình khái niệm
Sơ đồ mang tính khái niệm. Schema vật lý cuối, ràng buộc và chuyển trạng thái vòng đời phải được đặc tả trong feature spec của Platform Core. ID Account/Workspace dùng string NanoID có prefix theo D-017 (acc_…, ws_…).
3. Loại Workspace
Personal Workspace
- Tạo cho tài khoản cá nhân.
- Phù hợp ứng dụng cá nhân và subscription cá nhân.
- Owner là MINAP Account liên kết.
- Có thể là workspace mặc định sau onboarding.
Organization Workspace
- Do một account tạo hoặc chuyển theo workflow chuyển ownership tường minh.
- Có tên, hồ sơ, thành viên và cấu hình cấp nền tảng riêng.
- Hỗ trợ mời và gỡ thành viên.
- Một người có thể thuộc nhiều Organization Workspaces.
4. Các lớp authorization
- Platform identity: Tài khoản đã authenticated và đang active?
- Workspace membership: Tài khoản là thành viên active của Workspace được yêu cầu?
- Application access: Application đã được bật cho Workspace đó?
- Application authorization: Tài khoản có role/permission Application cần thiết?
- Resource assignment: Tài khoản được gán vào resource cụ thể (ví dụ tenant được gán vào phòng)?
Platform roles và Application roles là tách biệt. Workspace Owner không tự động được ủy quyền mọi hành động domain trừ khi chính sách của Application ánh xạ tường minh vai trò đó.
5. Ví dụ: quản lý nhà trọ
- Owner tạo Organization Workspace.
- Owner bật Application liên quan.
- Owner tạo phòng và gán tenant.
- Tenant tham gia Workspace và được gán vào một phòng.
- Tenant xem được các bản ghi tiền thuê, điện, nước và phí được phép.
- Tenant không được xem bản ghi riêng tư của tenant khác.
Ví dụ này minh họa vì sao phải có authorization cấp resource ngoài Workspace membership.
6. Gắn entitlement
Hỗ trợ cả hai:
- Entitlement cấp Account: phù hợp định giá dùng cá nhân.
- Entitlement cấp Workspace: phù hợp định giá doanh nghiệp/đội nhóm.
Application định nghĩa subject entitlement nào áp dụng. Platform Core đánh giá entitlement; Application thực thi giới hạn và tính năng theo domain dựa trên hợp đồng trả về.
7. Yêu cầu tích hợp Keycloak
- Dùng Keycloak subject (
sub) ổn định làm tham chiếu identity ngoài map sang MINAP Accountacc_…; không dùng email hoặc Keycloaksublàm primary id công khai của MINAP Account. - Định nghĩa các flow liên kết tài khoản, đổi email, vô hiệu hóa tài khoản, đặt lại mật khẩu và liên kết federated IdP (Google MVP; mở rộng Apple / Microsoft / GitHub / … trên Keycloak Identity Brokering).
- Reference id của từng social provider (Apple/GitHub/…) do Keycloak lưu và quản lý. Platform Core chỉ map một Keycloak
sub→acc_…— không bảng/accountscolumns theo từng provider. - UI “tài khoản liên kết”: danh sách IdP đã link, link thêm, revoke — đọc/ghi qua Keycloak (Account Console và/hoặc Account/Admin API). Không nhân bản danh sách federated vào Platform Core DB; audit platform (nếu cần) chỉ ghi sự kiện sau khi IdP xác nhận.
- Định nghĩa riêng flow redirect trình duyệt và flow authorization native/mobile.
- Dùng Authorization Code + PKCE cho public clients khi phù hợp.
- Xác thực issuer, audience, signature, expiry và nonce/state khi áp dụng.
- Định nghĩa yêu cầu refresh-token rotation/revocation, logout, thu hồi session/device và back-channel logout.
- Phiên đăng nhập đa thiết bị: SoT = Keycloak user sessions. Xem danh sách / đăng xuất một phiên hoặc tất cả = thao tác trên Keycloak (Account Console hoặc API). Platform Core không giữ bảng session active làm SoT; optional
last_login_at/audit_eventschỉ tóm tắt hoặc audit, không thay revoke IdP. - Giữ authorization account/workspace nền tảng trong Platform Core hoặc module authorization có chủ sở hữu rõ; không nhồi mọi permission nghiệp vụ Application vào Keycloak realm roles.
8. Quan hệ với Application credentials (D-018)
- User authentication (tài liệu này): session OIDC Keycloak cho người (
acc_…). - Application authentication (xem
09-platform-sdk-and-application-contracts.md§5): Platform Core cấp credential cho Application đã đăng ký (app_…+ token) dùng bởi Application backend và client API của Platform SDK. - Không dùng Application credential thay user session; không nhúng secret Application dài hạn vào public client.
- Composition (on-behalf-of: app hành động kèm ngữ cảnh user) còn OPEN đến khi hợp đồng API yêu cầu.
9. Hạng mục thiết kế còn mở
- Chiến lược realm: một realm versus nhiều realms.
- Topology client Keycloak cho shell và Applications.
- Thiết kế đăng nhập native mobile và deep-link callback.
- Chấp nhận lời mời tổ chức và chuyển ownership.
- Xóa tài khoản, xuất dữ liệu và chính sách retention.
- Biểu diễn role/permission chính xác và chiến lược cache/invalidation.
- Có / khi nào cần composition user + Application credential (on-behalf-of).