Integration Specification: INT-001 – Hệ thống Xác thực Tập trung¶

Phiên bản: 1.2 Ngày tạo: 2026-04-01 Cập nhật: 2026-04-08 – Làm rõ ứng dụng là consumer; dual-mode là trách nhiệm của SSO Trạng thái: 📝 Draft Ready

1. Overview¶

1.1 Business Purpose¶

Cung cấp cơ chế đăng nhập tập trung cho tất cả người dùng từ các Sở/Ban/Ngành thuộc Thành phố. Ứng dụng chỉ là consumer (Service Provider) — không tự quản lý xác thực mà uỷ quyền hoàn toàn cho hệ thống SSO bên ngoài.

Từ góc nhìn ứng dụng: - Khi user truy cập → redirect đến SSO để xác thực - Sau xác thực thành công → SSO trả về identity (email, đơn vị, tên) - Ứng dụng nhận identity → mapping với user nội bộ → phân quyền → cho phép truy cập - Ứng dụng không quan tâm user đăng nhập bằng phương thức nào (username/password hay tài khoản công vụ) — đó là trách nhiệm của SSO

Về phía SSO: - SSO hỗ trợ dual-mode authentication: username/password (giai đoạn demo) và tài khoản công vụ/VNeID (khi pháp lý sẵn sàng) - Hai phương thức có thể chạy song song — đây là cấu hình phía SSO, không ảnh hưởng code ứng dụng - Giả định SSO là Keycloak (có thể thay đổi — ứng dụng cần thiết kế abstraction layer)

Use Case	Mô tả	Vai trò
UC-AUTH-001	Đăng nhập hệ thống	Tất cả actors

1.3 In Scope / Out of Scope¶

In Scope (phía ứng dụng — consumer):

Redirect user đến SSO khi chưa có session hợp lệ
Nhận identity từ SSO sau xác thực: email, username, đơn vị
Mapping identity SSO với user nội bộ (email là mapping key)
Auto-provision: tạo user mới nếu chưa có trong DB nội bộ
Session management phía ứng dụng
Single Logout (nếu SSO hỗ trợ)

Out of Scope (trách nhiệm của SSO, không phải ứng dụng):

Quản lý phương thức xác thực (username/password, SAML, VNeID...) — việc của SSO
Quản lý tài khoản trên SSO (tạo/xóa user trên IdP) — việc của SSO admin
Cấu hình dual-mode, migration từ local sang tài khoản công vụ — việc của SSO admin
Phân quyền vai trò (quản lý nội bộ trong hệ thống — xem Role Matrix)

2. Existing System Constraints¶

2.1 Systems Involved¶

Hệ thống	Vai trò	Ghi chú
Hệ thống SSO (giả định Keycloak)	Identity Provider (IdP)	Quản lý xác thực, hỗ trợ dual-mode. Triển khai on-premise
Hệ thống Quản trị Dữ liệu (ứng dụng này)	Service Provider (Consumer)	Chỉ nhận identity sau xác thực — không tự xác thực
SSO Thành phố (VNeID/tài khoản công vụ)	External IdP (tuỳ chọn)	Được cấu hình trong SSO khi pháp lý sẵn sàng — ứng dụng không cần biết

2.2 Dependency Constraints¶

Ứng dụng phụ thuộc hoàn toàn vào SSO để xác thực — nếu SSO gián đoạn, không user nào đăng nhập được
SSO hỗ trợ dual-mode: giai đoạn demo dùng username/password, sau đó bổ sung tài khoản công vụ — không thay đổi code ứng dụng
Triển khai On-premise — SSO và ứng dụng cùng mạng nội bộ
Cần thiết kế SSO abstraction layer phía ứng dụng để thay đổi IdP (Keycloak → CAS → khác) không ảnh hưởng logic nghiệp vụ

3. Interaction Scenarios¶

3.1 Trigger and Preconditions¶

Trigger	Preconditions
User truy cập URL hệ thống và chưa có session hợp lệ	SSO đang hoạt động; user có tài khoản trên SSO; trình duyệt hỗ trợ redirect

3.2 Main Business Flow (góc nhìn ứng dụng)¶

User → [Truy cập hệ thống] 
     → [Ứng dụng redirect đến SSO]
     → [SSO xác thực user (bằng phương thức nào là việc của SSO)]
     → [SSO trả về identity: email, username, đơn vị]
     → [Ứng dụng nhận identity, tạo session]
     → [Tra cứu user theo EMAIL trong DB nội bộ]
        → Nếu tìm thấy (Admin đã pre-provision): load vai trò đã gán
        → Nếu không tìm thấy: tạo user mới, trạng thái "chưa phân quyền"
     → [Redirect đến Dashboard SCR-DASH-10]

Lưu ý: Luồng trên áp dụng cho mọi phương thức xác thực (username/password hay tài khoản công vụ). Ứng dụng xử lý identity y hệt nhau — không phân biệt.

3.3 Alternative/Error Flows¶

Scenario	Xử lý
SSO không phản hồi	Hiển thị trang lỗi "Hệ thống xác thực không khả dụng – vui lòng thử lại sau"
User không có tài khoản SSO	SSO từ chối → hiển thị thông báo lỗi trên trang SSO
Identity trả về không hợp lệ (thiếu email)	Ứng dụng từ chối → redirect lại SSO
User có tài khoản SSO nhưng chưa được Admin gán vai trò	Đăng nhập thành công nhưng hiển thị "Chưa được phân quyền – liên hệ Admin"
Session timeout	Redirect đến SSO để xác thực lại

4. Business Data Contract¶

4.1 Outbound Data (Ứng dụng → SSO)¶

Dữ liệu	Mô tả	Ghi chú
Authentication Request	Yêu cầu xác thực	Gửi khi redirect user đến SSO. Giao thức cụ thể (SAML/OAuth) tuỳ SSO
Logout Request	Yêu cầu đăng xuất	Khi user logout khỏi ứng dụng

4.2 Inbound Data (SSO → Ứng dụng)¶

Dữ liệu	Mô tả	Bắt buộc	Ghi chú
email	Email người dùng	Có	Mapping key — dùng để liên kết identity SSO với user nội bộ
username	Tên đăng nhập	Có	Định danh trên SSO
organization_unit	Mã/tên đơn vị (Sở/Ban/Ngành)	Có	Dùng để map user với cây tổ chức
display_name	Họ tên hiển thị	Không	Nếu SSO cung cấp

Lưu ý: SSO không cung cấp vai trò (Data Owner/Manager/Approver/Staff/Admin). Vai trò được Admin gán nội bộ trong hệ thống.

4.3 Validation and Mapping Rules¶

Rule	Mô tả
User mapping	Khi nhận identity từ SSO, hệ thống tra cứu user theo email (mapping key). Tìm thấy → liên kết, load vai trò. Không tìm thấy → tạo mới với trạng thái "chưa phân quyền"
Org mapping	`organization_unit` từ SSO được map với cây tổ chức đã khai báo (UC-SYS-003)
Role assignment	Không tự động từ SSO — Admin pre-provision hoặc gán vai trò thủ công (UC-SYS-002)
Pre-provisioning	Admin tạo user trước (email, tên, đơn vị, vai trò) để khi user đăng nhập lần đầu đã có vai trò sẵn

5. Operational Rules¶

5.1 SLA / Rate Limit / Cut-off¶

Metric	Giá trị	Ghi chú
Availability	Giả định 24/7	SSO luôn available
Response time	< 3 giây cho luồng login hoàn chỉnh	Bao gồm redirect + xác thực + callback
Concurrent users	Hàng nghìn	Phù hợp quy mô Thành phố

5.2 Error Handling / Retry / Fallback¶

Tình huống	Xử lý
SSO không phản hồi	Hiển thị trang lỗi, không có fallback phía ứng dụng

Ghi chú: Dual-mode (username/password fallback khi SSO bên ngoài gián đoạn) là trách nhiệm phía SSO, không phải ứng dụng.

5.3 Audit and Monitoring Expectations¶

Loại	Mô tả
Audit log	Ghi nhận mỗi lần đăng nhập: user, thời điểm, IP, kết quả (thành công/thất bại)
Monitoring	Alert nếu SSO response time vượt ngưỡng hoặc tỉ lệ lỗi xác thực tăng bất thường

6. Open Questions and Assumptions¶

Assumption ID	Statement	Impact	Status	User Confirmation
ASM-INT-001	SSO giả định là Keycloak, có thể thay bằng hệ thống khác. Ứng dụng cần SSO abstraction layer để thay đổi IdP không ảnh hưởng logic	Medium	Confirmed	2026-04-01
ASM-INT-002	SSO cung cấp identity only (email, username, đơn vị). Vai trò quản lý nội bộ trong ứng dụng	Medium	Confirmed	2026-04-01
ASM-INT-005	SSO luôn available. Nếu SSO gián đoạn, ứng dụng không có cơ chế fallback riêng	Low	Confirmed	2026-04-01
ASM-INT-011	SSO hỗ trợ dual-mode: username/password (demo) + tài khoản công vụ (khi pháp lý sẵn sàng). Đây là cấu hình phía SSO — ứng dụng không cần thay đổi code	Medium	Confirmed by BA Lead	2026-04-08

7. Dependencies and Impact¶

Related Roles (Role Matrix IDs): RM-001 đến RM-005 (tất cả vai trò đều cần đăng nhập)
Related Use Cases: UC-AUTH-001
Related Screen Flows: SCR-AUTH-10 (Đăng nhập)
Design Constraint: Ứng dụng cần SSO abstraction layer — chỉ nhận identity, không quan tâm phương thức xác thực

Last Updated: 2026-04-08