# Core `cp-identity` — Định danh & SSO

> 07/7/2026 · Repo: **controlplane** · Đánh giá: **✅ Nền tốt · ⚠ 2 điểm cache** · Bản HTML: [cp-identity.html](cp-identity.html) · [Review tổng core](core-review-2026-07-07.md)

## 1. Vai trò
Lớp định danh toàn cục: **User, GlobalSession, OAuth2 authorization-code** — đăng nhập một lần ở Control Plane, vào nhiều workspace, mỗi workspace ký session cục bộ riêng.

## 2. Thành phần chính

| Thành phần | Vai trò |
|---|---|
| **User · GlobalSession** | Tài khoản toàn cục + phiên đăng nhập CP (cookie 7 ngày) |
| **AuthClient · AuthorizationCode** | OAuth2 client per-workspace · code TTL 60s đổi lấy identity |
| **authService · ssoService · globalSessionService** | Đăng ký/đăng nhập · cấp/đổi code · quản lý phiên |
| **Session workspace** | JWT cục bộ 24h — token WS A không dùng được ở WS B; CP check membership trước khi cấp |

## 3. Hiện trạng (đọc từ code)
- Luồng SSO đầy đủ và đúng chuẩn authorization-code; cô lập session theo workspace tốt
- Cross-check membership trước khi cấp token — chặn truy cập chéo
- ⚠ `permissionCache` rỗng sau khi BE restart → user non-super bị 403 tới khi re-login (ghi chú sẵn trong `authorize.js`)
- ⚠ Token PAT không nạp permission vào cache → chỉ super admin dùng được PAT

## 4. Khuyến nghị — tham chiếu hệ phổ biến

| Tham chiếu | Khuyến nghị |
|---|---|
| **Keycloak / Auth0** | Nhúng **permission claims (hoặc epoch)** vào JWT workspace, hoặc chuyển cache sang store bền (Redis/DB) — hết 403 sau restart, PAT hoạt động đúng |
| **Keycloak single-logout** | Bổ sung **logout lan truyền**: đăng xuất CP → vô hiệu session các workspace đang mở (hiện mỗi WS tự hết hạn 24h) |
| **OWASP** | Rate-limit đăng nhập + khóa tạm sau N lần sai (nếu chưa có) |

## 5. Liên kết trong core
- **cp-rbac** — nguồn permission đổ vào session
- **cp-workspace** — AuthClient sinh lúc provision
- **rt-authz** — engine đọc identity từ token


## Ma trận tác nhân × năng lực

Core không phải module nghiệp vụ — ma trận theo **tác nhân**, kèm cơ chế/quyền gate. R đọc · W thực hiện · A duyệt.

| Năng lực | Cơ chế / quyền gate | SUPER | OWNER/QTHT | DEV | SVC | USER |
|---|---|:--:|:--:|:--:|:--:|:--:|
| Đăng ký / đăng nhập CP | form + rate-limit | — | — | — | — | W |
| Global session (của mình) | cookie og_global_session | R | — | — | — | W (logout) |
| Quản lý user CP | quyền admin CP | W | — | — | — | — |
| Cấp authorization code / đổi token | OAuth2 client per-WS | — | — | — | W (đổi code) | khởi phát |
| Quản lý AuthClient | quyền admin CP | W | — | — | — | — |

SUPER = super admin CP · OWNER/QTHT = quản trị WS · DEV = developer/publisher · SVC = service-to-service · USER = người dùng cuối. Mục **(đích)** = theo khuyến nghị P1–P5.