🗃️ Auth Service Sub - Data Model v2.0¶

1. 📘 Mục tiêu & Phạm vi¶

Tài liệu này định nghĩa mô hình dữ liệu cho auth-service/sub, một service xác thực per-tenant trong hệ thống dx-vas. Việc thiết kế mô hình dữ liệu chuẩn xác là nền tảng để:

• Đảm bảo tính toàn vẹn, bảo mật và khả năng mở rộng của dữ liệu xác thực người dùng
• Phục vụ các thao tác xác thực OTP, Local Login, quản lý phiên đăng nhập, và thu hồi token
• Ghi nhận metadata cần thiết cho audit log, bảo vệ hệ thống khỏi gian lận
• Đảm bảo khả năng truy vết (traceability) và phân quyền truy cập theo chính sách RBAC

🎯 Mục tiêu cụ thể¶

• Thiết kế bảng dữ liệu auth_sessions chuẩn hóa, phản ánh đầy đủ vòng đời một phiên đăng nhập
• Định nghĩa cấu trúc cache revoked_tokens trên Redis dùng để thu hồi token chủ động
• Chuẩn hóa metadata gắn với session bao gồm ip_address, user_agent, device_type, location
• Phân loại và mô tả các giá trị ENUM quan trọng trong logic xác thực (auth_method, device_type, v.v.)
• Thiết lập chiến lược Retention & Anonymization nhất quán với toàn hệ thống
• Hỗ trợ kiểm thử và migration schema dễ dàng trên môi trường multi-tenant

📦 Phạm vi dữ liệu được quản lý¶

🚫 Ngoài phạm vi (Out of Scope)¶

🧭 Liên hệ kiến trúc tổng thể¶

Mô hình dữ liệu được thiết kế để vận hành tốt trong kiến trúc: - Multi-tenant per-instance (mỗi tenant có DB riêng hoặc schema riêng) - Stateless microservice (tất cả trạng thái xác thực được externalized) - Token-based auth (không lưu trạng thái user đăng nhập trong RAM) - RBAC externalized (quản lý quyền ngoài auth-service/sub)

2. 🧩 Tổng Quan Dữ Liệu & Mối Quan Hệ¶

Mô hình dữ liệu của auth-service/sub được thiết kế tối giản và hiệu quả, tập trung vào việc quản lý vòng đời phiên đăng nhập và việc thu hồi token, đồng thời ghi nhận đầy đủ metadata phục vụ cho audit, phân tích bảo mật và giám sát hành vi người dùng.

2.1. Sơ đồ ERD (Entity Relationship Diagram)¶

erDiagram

  AUTH_SESSIONS {
    UUID id PK
    UUID user_id
    TEXT auth_method
    TEXT device_type
    TEXT ip_address
    TEXT user_agent
    TEXT location
    TEXT session_status
    TIMESTAMP created_at
    TIMESTAMP expired_at
    TIMESTAMP revoked_at
    TEXT revoked_reason
    UUID tenant_id
  }

  REVOKED_TOKENS {
    TEXT jti PK
    UUID session_id FK
    UUID user_id
    TIMESTAMP revoked_at
    TEXT reason
    UUID tenant_id
  }

  AUTH_SESSIONS ||--o{ REVOKED_TOKENS : has

2.2. Giải thích mối quan hệ¶

✅ Mọi bảng đều có khóa chính rõ ràng, hỗ trợ phân vùng theo tenant_id nếu cần.

2.3. Ký hiệu & conventions¶

• UUID: Toàn bộ các khoá chính và liên kết đều dùng UUID để đảm bảo tính toàn cục và dễ trace.
• snake_case: Dùng thống nhất cho tên cột.
• tenant_id: Có mặt ở mọi bảng để đảm bảo khả năng lọc, truy xuất và bảo vệ tenant isolation.
• Timestamp: Luôn dùng timezone-aware timestamp (TIMESTAMPTZ nếu PostgreSQL).
• Trạng thái logic (như revoked_at, revoked_reason, session_status) dùng nullable field thay vì boolean flag — đảm bảo mở rộng về sau.

🧠 Ghi chú thiết kế¶

• Không có bảng users trong service này – mọi thông tin user được đồng bộ từ user-service.
• Cache revoked_tokens trên Redis có thể phản ánh một phần dữ liệu từ DB để tối ưu tra cứu runtime.
• Session metadata có thể phục vụ cho audit log, tracking đăng nhập bất thường, hoặc security scoring.

3. 📌 Bảng auth_sessions¶

Bảng auth_sessions ghi lại mọi phiên đăng nhập thành công của người dùng (qua OTP hoặc Local login), là cơ sở cho việc quản lý vòng đời xác thực, phục vụ kiểm tra bảo mật, thống kê hành vi người dùng và kiểm soát thu hồi token.

3.1. 🧾 Mục đích¶

• Lưu vết mỗi lần đăng nhập thành công
• Gắn metadata liên quan đến môi trường đăng nhập
• Liên kết với revoked_tokens để hỗ trợ revoke có mục tiêu
• Phục vụ thống kê đăng nhập và cảnh báo bảo mật
• Là nguồn dữ liệu chính cho hệ thống audit logging & observability

3.2. 📜 Cấu trúc SQL (PostgreSQL)¶

CREATE TABLE auth_sessions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL,
  tenant_id UUID NOT NULL,
  auth_method TEXT NOT NULL CHECK (auth_method IN ('otp', 'local')),
  session_status TEXT DEFAULT 'active', -- optional UI status
  ip_address TEXT,
  user_agent TEXT,
  device_type TEXT,
  location TEXT,
  created_at TIMESTAMPTZ DEFAULT now(),
  expired_at TIMESTAMPTZ,
  revoked_at TIMESTAMPTZ,
  revoked_reason TEXT
);

3.3. 📋 Mô tả các cột¶

3.4. 🔐 RBAC & Bảo mật theo cột¶

• Chỉ chính user (self) hoặc admin nội bộ có quyền đọc
• Cột ip_address, user_agent, location được đánh dấu là dữ liệu nhạy cảm theo adr-024
• Tất cả truy cập đọc phải đi qua lớp kiểm tra x-condition dựa trên user_id hoặc tenant_id

3.5. ⚡ Index & Constraint¶

3.6. 💡 Ví dụ bản ghi¶

{
  "id": "f2b9c6ae-4b78-4d99-b4ea-25db9c91a95c",
  "user_id": "7b6d3f56-25b9-42cf-9c29-631f6fd43a90",
  "tenant_id": "school-abc",
  "auth_method": "otp",
  "ip_address": "118.70.84.12",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_6)",
  "device_type": "mobile",
  "location": "Ho Chi Minh, VN",
  "created_at": "2025-06-13T10:32:20Z",
  "expired_at": "2025-06-13T12:32:20Z",
  "session_status": "active"
}

📌 Ghi chú:

• Trường expired_at thường được xác định bởi JWT TTL + policy
• Trường revoked_at có thể được gắn khi user logout hoặc bị revoke thủ công qua API
• Trường location là tuỳ chọn (nullable), thường được xác định từ IP phía frontend gửi về

4. 📌 Cache revoked_tokens (Redis)¶

Hệ thống sử dụng Redis như một bộ nhớ đệm phân tán để lưu thông tin các token đã bị thu hồi (revoked), giúp api-gateway và các service liên quan kiểm tra nhanh tính hợp lệ của token khi nhận request.

4.1. 🧾 Mục đích¶

• Truy vấn nhanh token có bị thu hồi hay không mà không cần truy cập DB
• Hỗ trợ người dùng logout chủ động trên mọi thiết bị
• Hạn chế token reuse hoặc abuse khi xảy ra mất mát thiết bị

4.2. 🧩 Cấu trúc Redis Key-Value¶

📌 Ví dụ giá trị Redis:

{
  "revoked_at": "2025-06-13T10:40:00Z",
  "reason": "user_logout",
  "session_id": "f2b9c6ae-4b78-4d99-b4ea-25db9c91a95c",
  "user_id": "7b6d3f56-25b9-42cf-9c29-631f6fd43a90"
}

4.3. ♻️ TTL và chính sách dọn dẹp¶

• Mỗi token được lưu kèm TTL = expiration_time - now
• Token đã hết hạn sẽ tự động bị Redis xoá
• Không cần migration hay cleanup định kỳ

📌 Nếu dùng Sliding TTL hoặc Refresh token rotation, phải bảo đảm TTL đủ dài để bao phủ thời gian kiểm tra replay.

4.4. 🔁 Tương tác trong lifecycle¶

Tất cả service consumer (gateway, audit, CRM adapter…) phải check revoked cache trước khi xử lý logic nếu thấy token hợp lệ về mặt signature.

4.5. 🚨 Lưu ý triển khai¶

• Redis phải được cấu hình HA, persistence và TTL-aware eviction policy
• Thực hiện bằng Redis Cluster nếu có hơn 50k tenant/token active
• Mọi key đều phải được prefix revoked: để phân biệt namespace rõ ràng
• Redis sử dụng db-index riêng nếu chia cho nhiều dịch vụ
• Không dùng để backup token – chỉ để kiểm tra tính hợp lệ tức thời

📌 Ghi chú bảo mật:

• Thông tin lưu trong Redis không chứa JWT gốc
• Dữ liệu nhạy cảm như session_id có thể được ẩn hoặc mã hóa nếu chia sẻ multi-tenant cluster
• Redis phải nằm sau firewall hoặc private subnet trong hạ tầng cloud

5. 🧩 Session Metadata¶

Mỗi phiên đăng nhập (auth_session) được gắn kèm metadata phản ánh ngữ cảnh truy cập của người dùng. Những dữ liệu này giúp tăng cường bảo mật, hỗ trợ phân tích hành vi, và phục vụ cho các hệ thống quan sát (observability) & kiểm toán (audit).

5.1. 📋 Danh sách các trường metadata¶

5.2. 🧠 Nguồn gốc dữ liệu¶

• Các trường này được thu thập từ frontend hoặc middleware tại gateway
• Sau đó đính kèm vào payload gửi đến auth-service/sub trong quá trình login
• Được ghi trực tiếp vào bảng auth_sessions hoặc lưu kèm audit log

5.3. 🛡 Bảo mật & xử lý dữ liệu nhạy cảm¶

Mọi metadata đều phải tuân theo chiến lược anonymization hoặc masking khi lưu lâu dài hoặc gửi sang hệ thống ngoài.

5.4. 📈 Sử dụng trong hệ thống¶

• Được gắn vào mỗi bản ghi auth_sessions
• Gửi lên Pub/Sub khi phát sinh sự kiện auth.token.issued hoặc auth.token.revoked
• Làm chỉ số chính trong dashboard theo dõi đăng nhập (Prometheus/Grafana)
• Sử dụng để phát hiện đăng nhập bất thường, login từ quốc gia bất thường, thiết bị lạ

5.5. 💡 Gợi ý mở rộng tương lai¶

• Trích xuất fingerprint hoặc session hash để xác định danh tính thiết bị
• Liên kết với alert system khi đăng nhập từ IP blacklist hoặc bị nghi ngờ

{
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "ip_address": "203.113.135.42",
  "device_type": "web",
  "location": "Ha Noi, VN",
  "login_context": {
    "app_version": "1.2.3",
    "mfa_completed": true
  }
}

✅ Việc lưu metadata chính xác và bảo vệ đúng mức sẽ giúp hệ thống auth-service/sub vừa an toàn, vừa giàu khả năng quan sát mà không vi phạm quyền riêng tư người dùng.

6. 🧾 ENUMs & Constants¶

Các giá trị ENUM giúp chuẩn hóa và giới hạn phạm vi đầu vào hợp lệ trong quá trình xác thực, đồng thời hỗ trợ hiển thị trạng thái rõ ràng trong hệ thống quản trị hoặc giao diện frontend.

6.1. 📌 auth_method¶

Xác định phương thức xác thực mà người dùng sử dụng để đăng nhập.

📌 Sử dụng trong: bảng auth_sessions, OpenAPI schema LoginRequest.

6.2. 📌 device_type¶

Phân loại thiết bị từ frontend giúp phân tích hành vi và phát hiện đăng nhập bất thường.

📌 Sử dụng trong: auth_sessions.device_type

6.3. 📌 session_status¶

Dùng nội bộ để hiển thị trạng thái phiên đăng nhập trong giao diện admin.

📌 Không ảnh hưởng tới xác thực token – token validity được kiểm tra riêng.

6.4. 📌 error.code¶

Theo chuẩn adr-011, mọi response lỗi đều bao gồm error.code dạng định danh ngắn, giúp frontend hoặc hệ thống quản trị hiển thị và xử lý dễ dàng hơn.

📌 Tất cả mã lỗi phải nằm trong danh sách được định nghĩa trước (xem thêm error-codes.md).

🧩 Gợi ý mở rộng¶

• Các enum nên được central hóa trong file schemas/constants.py (Python), constants.ts (TypeScript), hoặc đặt trong schema validator (OpenAPI/JSON Schema)
• Hỗ trợ tự động sinh document và kiểm thử dựa trên enum list (contract testing)

7. 🔐 Data Access Control (RBAC)¶

Tất cả dữ liệu trong auth-service/sub đều được bảo vệ bởi cơ chế Role-Based Access Control (RBAC) động, với điều kiện (x-condition) được kiểm tra tại api-gateway hoặc middleware RBAC trước khi request đến được service.

7.1. 🧩 Chính sách RBAC áp dụng¶

7.2. 📌 Kiểm tra điều kiện (x-condition)¶

Việc cấp quyền không chỉ phụ thuộc vào permission string mà còn phụ thuộc vào điều kiện kèm theo như sau:

📌 Các x-condition được mô tả rõ trong interface-contract.md ở phần x-condition và được enforced tại api-gateway.

7.3. 🔒 Áp dụng vào mô hình dữ liệu¶

Tất cả truy cập trực tiếp vào bảng cần đi qua lớp RBAC filter (hoặc được kiểm tra trước ở gateway).

7.4. 🧠 Best Practices¶

• Không trả session người khác kể cả admin nếu chưa kiểm RBAC kỹ
• Dùng x-condition trên cả tenant và user scope để giảm rủi ro rò rỉ chéo tenant
• Mọi sự kiện đọc/ghi nhạy cảm nên được ghi vào audit log kèm actor_id, trace_id

📌 Ví dụ:

"x-permissions": ["session.read:self"],
"x-condition": {
  "user_id": "{{current_user.id}}",
  "tenant_id": "{{X-Tenant-ID}}"
}

✅ Hệ thống RBAC động như vậy đảm bảo khả năng kiểm soát tinh vi nhưng vẫn linh hoạt để mở rộng, đặc biệt quan trọng trong hệ thống multi-tenant như dx-vas.

8. 🕒 Data Lifecycle & Retention Policy¶

Mọi dữ liệu liên quan đến xác thực trong auth-service/sub đều được gắn liền với vòng đời xác định rõ ràng và chính sách xử lý dữ liệu sau khi hết hạn. Điều này đảm bảo hệ thống vừa tuân thủ các quy định bảo mật (như GDPR), vừa tối ưu chi phí lưu trữ và hiệu năng.

8.1. ♻️ Retention Policy theo loại dữ liệu¶

📌 Lưu ý: TTL thực tế có thể được cấu hình theo tenant-level policy hoặc quy định hệ thống.

8.2. 🔐 Anonymization theo adr-024¶

Dữ liệu sau khi hết TTL sẽ được ẩn một phần (mask) hoặc ẩn toàn bộ như sau:

📌 Một job nền (retention_worker) sẽ thực hiện xoá hoặc làm mờ định kỳ.

8.3. 🔥 Chính sách xóa cứng (Hard Delete)¶

Theo adr-026, hệ thống không cho phép xóa bản ghi session thủ công từ API. Xoá cứng chỉ được thực hiện:

• Tự động khi đạt TTL
• Qua job batch định kỳ có kiểm soát (background cron job)
• Không cho phép xóa bản ghi riêng lẻ từ phía người dùng

8.4. 🧠 Gợi ý vận hành¶

• Nên lưu phiên bản đã anonymize lâu hơn (ví dụ: giữ 12 tháng thay vì 6 nếu đã xoá nhạy cảm)
• Cho phép admin xem dữ liệu anonymized để phục vụ phân tích, thống kê
• Với tenant VIP có yêu cầu lưu lâu hơn, có thể cấu hình TTL riêng (cần mở rộng job)

8.5. Ví dụ biểu đồ lifecycle¶

graph LR
  login[Phiên đăng nhập thành công] --> alive[Trong 180 ngày]
  alive --> anonymized[Được làm mờ dữ liệu nhạy cảm]
  anonymized --> expired[Xoá khỏi DB sau 12 tháng]

✅ Chính sách vòng đời rõ ràng giúp hệ thống vừa tiết kiệm tài nguyên, vừa đảm bảo quyền riêng tư và kiểm soát dữ liệu tốt theo tiêu chuẩn cao nhất.

9. 🔁 Migration & Schema Evolution¶

Việc phát triển lâu dài của auth-service/sub yêu cầu khả năng mở rộng và cập nhật schema dữ liệu một cách an toàn, không gián đoạn, và tương thích với các tenant đang hoạt động. Tài liệu này định nghĩa chiến lược migration nhất quán theo ADR-023.

9.1. 📘 Tuân theo mô hình 3-phase migration¶

Mọi thay đổi về schema (thêm/sửa/xóa cột, index…) phải tuân thủ mô hình migration an toàn:

📌 Không bao giờ combine DROP & ADD trong cùng một migration nếu đang chạy trên nhiều tenant.

9.2. 🧱 Công cụ & best practices¶

9.3. 🚧 Kiểm thử migration¶

Mỗi thay đổi phải kèm checklist kiểm thử:

• ✅ Unit test với schema mới
• ✅ Chạy migration test trên sandbox với dữ liệu thật (một số tenant)
• ✅ Snapshot schema trước & sau để kiểm tra diff
• ✅ So khớp rollback (nếu có) hoặc backup trước khi deploy

📌 Các test nên được mô tả cụ thể tại docs/tests/db-migration/

9.4. 🛠 Multi-Tenant Considerations¶

9.5. 🧠 Gợi ý mở rộng¶

• Áp dụng flag db_version theo tenant để kiểm soát trạng thái migration
• Xây dựng dashboard theo dõi migration status per tenant
• Dùng canary tenant để test trước với schema mới

✅ Với chiến lược migration bài bản như trên, hệ thống auth-service/sub có thể mở rộng và nâng cấp liên tục mà không gây downtime hay mất dữ liệu – đúng định hướng zero-downtime của toàn kiến trúc dx-vas.

10. ✅ Kiểm thử liên quan dữ liệu¶

Việc kiểm thử toàn diện mô hình dữ liệu là yếu tố bắt buộc để đảm bảo độ ổn định, tính đúng đắn và khả năng mở rộng của auth-service/sub. Mục tiêu là đảm bảo mọi thay đổi đều được kiểm soát và phản ánh chính xác qua cả schema, API và hành vi runtime.

10.1. 🧪 Unit Tests (Database Layer)¶

10.2. 🔁 Integration Tests (Service Logic + DB)¶

📌 Cần có pre-seeded data test trên DB test riêng biệt cho các tenant giả lập.

10.3. 🔐 Security & Access Control Tests¶

10.4. 🧾 Contract Testing (Schema & API)¶

Theo adr-010, toàn bộ schema và API phải được kiểm thử bằng:

• ✅ JSON Schema validation (OpenAPI → Test Generator)
• ✅ revoked_tokens format đúng key prefix & value
• ✅ Các response luôn theo chuẩn ErrorEnvelope, ResponseMeta

📌 Test sử dụng tool như Dredd, Schemathesis, hoặc tích hợp Postman/Newman nếu cần.

10.5. 🧪 Migration & Data Retention Tests¶

✅ Tất cả các test đều phải được tích hợp CI/CD (GitHub Actions hoặc GitLab CI), chạy tự động theo PR và giai đoạn release, giúp đảm bảo không ai có thể merge mà không qua kiểm thử dữ liệu đầy đủ.

11. 📚 Tài liệu liên quan¶

• Interface Contract
• OpenAPI Spec
• Design
• ADR-004 - Security
• ADR-012 - Response Structure
• ADR-030 - Event Schema Governance