Đặc tả Tính năng: Định danh & SSO
1. Tổng quan & Tầm nhìn
Định danh & SSO là nhịp đập bảo mật của nền tảng VENI-AI. Nó cung cấp trải nghiệm đăng nhập thống nhất, quản lý phiên làm việc của người dùng trên các micro-frontend và xử lý sự phức tạp của các nhà cung cấp danh tính bên ngoài, đảm bảo một phiên làm việc an toàn duy nhất cho toàn bộ nền tảng.
2. Các Vai trò & Bên liên quan
| Vai trò | Mục tiêu |
|---|---|
| Người dùng cuối | Truy cập liền mạch vào tất cả các ứng dụng được ủy quyền với một lần đăng nhập. |
| Quản trị viên Tổ chức | Thực thi SSO doanh nghiệp và quản lý truy cập của thành viên. |
| Quản trị viên Hệ thống | Cấu hình các nhà cung cấp danh tính toàn cầu và các chính sách bảo mật. |
3. Câu chuyện Người dùng (User Stories)
- Với tư cách là thành viên, tôi muốn đăng nhập qua Google để không phải nhớ thêm một mật khẩu khác.
- Với tư cách là quản trị viên, tôi muốn thu hồi phiên làm việc của người dùng ngay lập tức khi họ rời công ty.
4. Yêu cầu Chức năng (FR)
- REQ-SSO-001: Hỗ trợ đa nhà cung cấp OAuth2/OIDC (Google, Keycloak).
- REQ-SSO-002: Cơ chế dự phòng xác thực cục bộ (Email/Mật khẩu).
- REQ-SSO-003: Cấp phát RS256 JWT an toàn trên toàn nền tảng.
- REQ-SSO-004: Cơ chế trao đổi token cho các JWT giới hạn phạm vi dịch vụ.
5. Yêu cầu Phi chức năng (NFR)
- Độ trễ: Xác thực cục bộ hoàn thành trong < 50ms.
- Bảo mật: Bắt buộc sử dụng PKCE cho tất cả các luồng client công khai.
- Độ tin cậy: Độ sẵn sàng 99.99% cho điểm cuối JWKS.
6. Logic & Quy tắc Nghiệp vụ
- Khớp Tên miền: Tự động liên kết tổ chức dựa trên tên miền email đã xác thực.
- Thời hạn Phiên: Access token (Ngắn hạn); Refresh token (Dài hạn).
- Thu hồi: Đưa chữ ký token vào danh sách đen trong Redis khi đăng xuất.
- Kiểm soát Trạng thái: Chỉ người dùng có trạng thái
ACTIVEmới có thể xác thực. Cá nhân ở trạng tháiSUSPENDEDbị chặn tại cấp cổng đăng nhập.
7. Giao diện Người dùng (UI/UX)
- Trang đăng nhập tập trung với các nút xác thực mạng xã hội phản hồi nhanh.
- "Trình chuyển đổi Danh tính" cho người dùng thuộc nhiều tổ chức.
- Trạng thái tải cho các chuyển hướng OIDC và bắt tay trao đổi token.
8. Kiến trúc Thông tin
- Một phần của "Trung tâm Định danh" Shell.
- Được hiển thị qua menu người dùng trên thanh công cụ của Shell.
9. Mô hình Dữ liệu & Lưu trữ
- Các bảng:
identity_providers,oauth_accounts,user_credentials. - Cache: Redis cho siêu dữ liệu phiên và danh sách đen token.
10. Lớp API & Dịch vụ
GET /api/auth/providersPOST /api/auth/exchangeGET /api/.well-known/jwks.json
11. Các Mẫu Tích hợp
- BroadcastChannel: Được sử dụng để đồng bộ JWT từ Shell Host sang các MFE động.
- Connect Protocol: Trao đổi tương thích gRPC cho bảo mật S2S.
12. Bảo mật & Quyền hạn
- Bắt tay RSA: Khóa công khai được công bố qua JWKS để xác thực phân tán.
- Cô lập: JWT bao gồm các claim
organizationIdđể lọc cơ sở dữ liệu bắt buộc.
13. Xử lý Lỗi & Khả năng Phục hồi
- Trang lỗi thân thiện khi "Nhà cung cấp không khả dụng".
- Phản hồi
401 Unauthorizedtiêu chuẩn với các mã chẩn đoán.
14. Hiệu năng & Khả năng Mở rộng
- Khóa công khai JWKS được cache toàn cầu trên tất cả các module satellite.
- Xác thực JWT không trạng thái tránh việc truy vấn cơ sở dữ liệu trên mỗi yêu cầu.
15. Toàn cầu hóa & Bản địa hóa
- Hỗ trợ các lỗi đăng nhập được bản địa hóa (EN/VI).
- Hỗ trợ RTL cho các widget định danh (dự kiến).
16. Khả năng Tiếp cận (a11y)
- Các biểu mẫu đăng nhập tuân thủ WCAG 2.2 (nhãn ARIA, tiêu điểm bàn phím).
- Hỗ trợ trình đọc màn hình trong chuỗi chuyển hướng OAuth.
17. Khả năng Quan sát & Phân tích
- Theo dõi "Các lần đăng nhập thất bại" để kiểm toán bảo mật.
- Phân tích về "Mức độ phổ biến của nhà cung cấp" (Google so với Cục bộ).
18. Kiểm thử & Chất lượng
- Máy chủ OIDC giả lập cho các bài kiểm tra tích hợp tự động.
- Kiểm thử E2E cho luồng Trao đổi Token giữa các MFE.
19. Các Ràng buộc & Giả định
- Yêu cầu kết nối ổn định đến các IdP bên ngoài để đăng nhập mạng xã hội.
- Giả định các module satellite triển khai xác thực JWT tiêu chuẩn.
20. Các Cải tiến Tương lai
- Hỗ trợ sinh trắc học (WebAuthn/Passkeys).
- MFA thích ứng dựa trên vị trí người dùng hoặc điểm rủi ro.