Bỏ qua

ADR-001: Keycloak là Auth Server duy nhất với xác thực Dual-mode

Trạng thái

Accepted

Ngày

2026-04-08

Người quyết định

Tech Lead

Architecture Drivers

D1 (Bảo mật & Tuân thủ), D4 (Đơn giản vận hành), D6 (Tốc độ đưa ra sản phẩm)

Bối cảnh

Hệ thống cần xác thực cho cán bộ chính phủ thuộc nhiều Sở/Ban/Ngành. Tích hợp SSO với VNeID/tài khoản công vụ yêu cầu hồ sơ pháp lý có thể mất 6+ tháng. Hệ thống phải sử dụng được trước khi SSO sẵn sàng, nhưng kiến trúc phải hỗ trợ SSO mà không thay đổi code.

Các Phương Án Xem Xét

Phương án A: Keycloak Dual-mode (local realm + SSO federation)

  • Ưu điểm: Một auth server xử lý cả hai luồng; zero code change khi SSO sẵn sàng; JWT format giống nhau bất kể phương thức auth; open-source được bảo trì tốt; hỗ trợ SAML 2.0 + OAuth 2.0
  • Nhược điểm: Keycloak là thành phần nặng (~512MB RAM); cần học quản trị Keycloak

Phương án B: Auth tự xây (Spring Security) + tích hợp SSO sau

  • Ưu điểm: Thiết lập ban đầu đơn giản hơn; không phụ thuộc bên ngoài
  • Nhược điểm: Phải viết lại auth khi SSO sẵn sàng; bảo trì kép; rủi ro bảo mật từ implementation tự xây

Phương án C: Auth0 / Okta (managed service)

  • Ưu điểm: Không có gánh nặng vận hành; tính năng enterprise
  • Nhược điểm: Cloud-based — vi phạm yêu cầu on-premise; chi phí recurring; vendor lock-in

Quyết Định

Sử dụng Phương án A: Keycloak Dual-mode. Keycloak chạy trong một realm duy nhất hỗ trợ cả username/password (local) và SSO (SAML 2.0 federation) đồng thời. Ứng dụng Spring Boot chỉ xác thực chữ ký JWT — không quan tâm JWT đến từ luồng nào.

Hệ Quả

Tích cực

  • Hệ thống sử dụng được ngay với local auth
  • Zero code change khi SSO sẵn sàng — chỉ cấu hình Keycloak admin
  • JWT format thống nhất đơn giản hóa logic phân quyền backend
  • Custom claims (org_id, unit_id) hoạt động với cả hai luồng qua Protocol Mappers

Tiêu cực

  • Keycloak thêm overhead vận hành (DB riêng, cập nhật, sao lưu)
  • Đội cần học quản trị Keycloak

Rủi ro

  • Nâng cấp phiên bản Keycloak có thể cần kiểm thử

Hành Động Tiếp Theo

  • Cấu hình Keycloak realm với local user store cho GĐ0
  • Chuẩn bị template cấu hình SAML 2.0 Identity Provider cho khi SSO sẵn sàng
  • Viết tài liệu runbook quản trị Keycloak

Liên Quan