📘 Thiết kế chi tiết auth-service/master¶

1. 🧭 Phạm vi & Trách nhiệm¶

1.1. 🎯 Mục đích¶

auth-service/master đóng vai trò là "Nhà Điều Phối Xác Thực" (Authentication Orchestrator) trong hệ sinh thái DX-VAS.
Nó chịu trách nhiệm xác minh danh tính người dùng qua các phương thức được hỗ trợ (Google OAuth2, OTP, Local) và điều phối các thành phần liên quan để hoàn tất quá trình đăng nhập.

1.2. ✅ Nằm trong phạm vi¶

• Xác thực danh tính người dùng qua các phương thức được hỗ trợ:
• ✅ Google OAuth2
• ✅ OTP (One-Time Password)
• ✅ Local (username/password)
• Lấy thông tin người dùng (email, name, avatar, user_id...) từ Google và đồng bộ với user-service.
• Gửi yêu cầu sinh token tới token-service thông qua API POST /v1/token/issue.
• Lưu audit log đăng nhập qua audit-service.
• Trả lại phản hồi chuẩn hóa (SuccessEnvelope, ErrorEnvelope) cho frontend hoặc API Gateway.

1.3. 🚫 Ngoài phạm vi¶

• ❌ Không tự tạo JWT token (ủy quyền cho token-service).
• ❌ Không lưu trữ session/token.
• ❌ Không quản lý RBAC hay introspect permission.
• ❌ Không xử lý logic liên quan đến magic link, OTP, hoặc xác thực 2 bước (2FA).

1.4. 👥 Người sử dụng chính¶

• Frontend client (qua OAuth2 redirect flow)
• API Gateway (gọi /me, /verify)
• token-service (được gọi tới từ đây)
• user-service (được truy vấn hoặc ghi đè user nếu chưa tồn tại)

2. 🌐 Thiết kế API chi tiết¶

2.1. 🔐 Nhóm: OAuth2 Authentication¶

🔄 Trong luồng POST /auth/exchange, sau khi xác thực thành công từ Google: 1. Gọi user-service để tra cứu/đồng bộ user. 2. Gọi token-service để phát hành access & refresh token.

2.2. 🙋 Nhóm: User Identity¶

2.3. 🧪 Nhóm: Internal & Testing¶

2.4. 📌 Ghi chú chung¶

• Các API chính đều tuân theo chuẩn SuccessEnvelope và ErrorEnvelope như mô tả trong ADR-011, ADR-012.
• Việc sinh token không nằm trong auth-service – thay vào đó, API /auth/exchange sẽ gọi token-service để lấy JWT và session_id.
• Các API /me và /verify phục vụ frontend và Gateway kiểm tra token.

Chi tiết: Interface Contract & OpenAPI

Dưới đây là phần đã viết lại cho mục ## 3. 📃 Mô hình dữ liệu trong auth-service/master/design.md, phản ánh đúng vai trò "điều phối xác thực", và tuân thủ chỉ thị là không mô tả session/token nội bộ, vì phần đó thuộc token-service.

3. 📃 Mô hình dữ liệu¶

3.1. Bảng auth_provider_config¶

Đây là bảng duy nhất auth-service/master thực sự quản lý trong DB nội bộ. Nó lưu thông tin cấu hình OAuth2 theo từng tenant, cho phép hệ thống mở rộng hỗ trợ nhiều nhà cung cấp xác thực trong tương lai.

🛡 Mọi access_token của Google sẽ chỉ được lấy nếu provider đó is_active.

3.2. Payload gọi token-service¶

Khi xác thực thành công và cần phát hành token, auth-service/master sẽ gửi payload sau đến token-service qua API POST /v1/token/issue:

{
  "user_id": "u123",
  "tenant_id": "vas-primary",
  "email": "user@example.com",
  "name": "Nguyễn Văn A",
  "avatar": "https://example.com/avatar.png",
  "grant_type": "google",
  "client_ip": "1.2.3.4",
  "user_agent": "Chrome/117"
}

📌 Đây là payload chuẩn hóa giữa các dịch vụ. token-service sẽ xử lý logic RBAC, sinh JWT, lưu session và trả lại access_token, refresh_token, expires_in, session_id.

• grant_type: là phương thức xác thực ban đầu của người dùng. Một trong:
• google
• otp
• local

3.3. Audit Logging¶

Mọi lần login thành công sẽ gửi event tới audit-service:

{
  "event": "auth.login.success",
  "user_id": "u123",
  "tenant_id": "vas-primary",
  "method": "google_oauth2",
  "timestamp": "2025-06-10T12:00:00Z"
}

📌 Lưu ý: Auth Service không chứa bảng users, không lưu token, không truy cập trực tiếp Redis. Các dữ liệu đó thuộc trách nhiệm của user-service và token-service.

👉 Chi tiết sơ đồ ERD, định nghĩa bảng và chiến lược kiểm thử dữ liệu được trình bày tại:
📂 Data Model

Dưới đây là nội dung chi tiết cho mục ## 4. 🔄 Luồng xử lý nghiệp vụ chính của auth-service/master/design.md, được viết lại theo mô hình điều phối xác thực hiện tại.

4. 🔄 Luồng xử lý nghiệp vụ chính¶

4.1. 🎯 Mục tiêu¶

Luồng xử lý tập trung vào việc xác thực danh tính người dùng qua Google OAuth2 và điều phối các dịch vụ liên quan để: - Đồng bộ thông tin người dùng vào user-service - Phát hành token thông qua token-service - Gửi log sự kiện xác thực tới audit-service

4.2. 🔁 Luồng: Google OAuth2 Login & Token Issue¶

sequenceDiagram
    participant Client
    participant AuthService
    participant Google
    participant UserService
    participant TokenService
    participant AuditService

    Client->>AuthService: GET /oauth2/login
    AuthService->>Google: Redirect đến Google OAuth2

    Google->>Client: Redirect callback + ?code
    Client->>AuthService: GET /oauth2/callback?code=...

    AuthService->>Google: Trao đổi access_token
    Google-->>AuthService: Trả userinfo

    AuthService->>UserService: POST /v1/users/global/sync
    UserService-->>AuthService: user_id

    AuthService->>TokenService: POST /v1/token/issue
    TokenService-->>AuthService: access_token, refresh_token, session_id

    AuthService->>AuditService: POST /v1/audit/event (auth.login.success)

    AuthService-->>Client: 200 OK + SuccessEnvelope

👉 Các luồng xác thực khác như OTP, Local login cũng tuân theo quy trình tương tự:
Xác minh → đồng bộ user → gọi token-service → gửi audit log.

4.3. 🧠 Diễn giải chi tiết¶

1. Bắt đầu OAuth2: Client gọi GET /oauth2/login → redirect đến Google.

2. Nhận mã xác thực: Google redirect về /oauth2/callback?code=... AuthService dùng code để lấy access_token và userinfo.

3. Đồng bộ thông tin người dùng: Gửi thông tin Google profile đến user-service để tìm hoặc tạo user (/v1/users/global/sync).

4. Yêu cầu phát hành token: Gửi user_id, tenant_id, và metadata đến token-service để sinh token.

5. Ghi log audit: Gửi event auth.login.success kèm user_id, method, tenant_id.

6. Trả kết quả cho client: Phản hồi gồm access_token, refresh_token, expires_in, session_id trong SuccessEnvelope.

4.4. ⚠️ Lưu ý đặc biệt¶

• Luồng này không sử dụng cookie session, chỉ hoạt động bằng JWT.
• Tất cả token và session đều được phát hành và quản lý bởi token-service.
• auth-service/master đóng vai trò điều phối thông minh, không giữ state.

5. 📣 Tương tác giữa các service¶

auth-service/master không hoạt động độc lập, mà là một trung tâm điều phối các tương tác xác thực với các dịch vụ lõi của hệ thống DX-VAS.

🔗 5.1. Google OAuth2 Provider¶

• Dùng để xác thực danh tính người dùng bằng OAuth2 Authorization Code Flow.
• Giao tiếp thông qua 2 bước:
• Redirect đến URL xác thực của Google (/oauth2/login)
• Gọi Google API để lấy access token và thông tin người dùng (/oauth2/callback)

🔗 5.2. user-service¶

• Đây là bước đảm bảo mọi người dùng đều có bản ghi đầy đủ trong hệ thống.
• Thao tác này là idempotent – có thể gọi nhiều lần mà không sinh bản ghi trùng.

> 🔁 Tất cả các phương thức xác thực (OAuth2, OTP, Local) đều gọi user-service để tìm hoặc tạo user.¶

🔗 5.3. token-service¶

• Nhận vào: user_id, tenant_id, client_ip, user_agent, grant_type.
• Trả ra: access_token, refresh_token, session_id, expires_in.

✅ Token chỉ được sinh nếu xác thực danh tính thành công và có user_id hợp lệ.

🔗 5.4. audit-service¶

• Gửi kèm: user_id, tenant_id, timestamp, grant_type, client_ip.

🔗 5.5. api-gateway¶

• Hai API này giúp Gateway introspect token một cách nhẹ, không cần decode hoặc gọi đến token-service.

📌 Tóm lại, auth-service/master: - Không giữ trạng thái, nhưng điều phối trạng thái qua các service khác. - Là điểm giao tiếp chính giữa thế giới ngoài (Google) và hệ thống nội bộ.

6. 🔐 Bảo mật & Phân quyền¶

🔐 6.1. Cơ chế bảo mật tổng thể¶

auth-service/master áp dụng mô hình bảo mật theo chuẩn zero-trust:

• ✅ OAuth2 redirect flow: sử dụng Google làm Identity Provider.
• ✅ JWT-based authentication: mọi truy cập từ frontend hoặc gateway đều dùng Authorization: Bearer.
• ✅ HTTPS-only: mọi endpoint đều được truy cập qua HTTPS, kể cả redirect và callback.
• ✅ Không giữ state người dùng: không dùng session hoặc cookie – mọi thông tin xác thực được kiểm chứng qua JWT.

🧩 6.2. Kiểm soát truy cập & Phân quyền¶

✅ Tất cả phân quyền động đều được kiểm soát ở cấp api-gateway. Auth service không cần tự tra quyền.

🧾 6.3. Header kiểm soát & Trace¶

Auth service xử lý và forward các header sau:

📜 6.4. Chính sách JWT¶

• issuer (iss): https://auth.truongvietanh.edu.vn
• audience (aud): dx-vas
• scope: chưa sử dụng, có thể mở rộng
• exp: được thiết lập bởi token-service, không can thiệp
• signature: sử dụng HS256 hoặc RS256, cấu hình tại token-service

⚠️ 6.5. Biện pháp chống giả mạo¶

• Không chấp nhận bất kỳ request có code hoặc token từ Google nếu không được xác thực trực tiếp qua callback URL hợp lệ.
• Callback URL phải match 100% redirect_uri đã đăng ký trong bảng auth_provider_config.
• Tự động kiểm tra nonce nếu triển khai OIDC.

✅ Bảo mật hệ thống không nằm ở auth-service riêng lẻ, mà ở sự phối hợp chuẩn hóa giữa auth-service, token-service và api-gateway.

7. ⚙️ Cấu hình & Phụ thuộc¶

🔧 7.1. Cấu hình môi trường (Environment Variables)¶

📦 7.2. Phụ thuộc hệ thống¶

🧱 7.3. Không phụ thuộc¶

Auth Service không phụ thuộc vào:

• Database quan hệ cho logic xác thực (chỉ dùng 1 bảng auth_provider_config)
• Redis (session và revoked token lưu ở token-service)
• Các công cụ 2FA, CAPTCHA (chưa tích hợp)

☁️ 7.4. Tích hợp triển khai (DevOps)¶

📌 Tất cả cấu hình nhạy cảm nên được inject thông qua Secret Manager hoặc môi trường CI/CD (GitHub Actions, GitLab, v.v.).

8. 🧪 Testing¶

Việc kiểm thử auth-service/master cần đảm bảo 3 tiêu chí: 1. Xác thực OAuth2 đúng chuẩn 2. Tích hợp đúng với user-service, token-service 3. Trả lỗi đúng chuẩn ErrorEnvelope, đúng trace_id

✅ 8.1. Unit Test¶

• Sử dụng: pytest, pytest-mock
• Coverage khuyến nghị: ≥ 90% core logic

🧪 8.2. Integration Test¶

• Có thể mock bằng httpx.MockTransport, requests-mock, hoặc wiremock cho local.

🌐 8.3. End-to-End Test (E2E)¶

• Khuyến khích dùng tool như Playwright, Postman, hoặc k6 để test tự động.

📋 8.4. Bộ test đặc biệt¶

📦 8.5. CI/CD Check¶

• ✅ Format chuẩn hóa theo black, flake8
• ✅ Test chạy qua pytest với coverage
• ✅ Swagger linter: spectral lint openapi.yaml

9. 📈 Observability¶

auth-service/master được thiết kế để dễ dàng giám sát, debug và truy vết lỗi, đảm bảo có thể quan sát toàn bộ luồng xác thực từ đầu đến cuối trong môi trường production.

📍 9.1. Logging¶

Mỗi request đều gắn trace_id (từ header hoặc sinh mới) và ghi log theo luồng.

📊 9.2. Metrics (Prometheus)¶

Có thể export metrics qua /metrics (tuỳ chọn bật qua config ENABLE_METRICS=true).

📝 9.3. Audit Logging¶

Audit log giúp điều tra post-mortem, phân tích hành vi người dùng và tuân thủ.

📈 9.4. Trace (OpenTelemetry)¶

Trace giúp hình dung được toàn bộ pipeline login: từ Google → user → token → audit

🔎 9.5. Alert Rule gợi ý¶

📌 Tất cả các log, metrics và trace cần phải được gắn trace_id để correlate đa chiều.

10. 🔁 Reliability¶

auth-service/master được thiết kế với triết lý stateless + fail-fast, nhằm đảm bảo khả năng phục hồi cao trong mọi tình huống xác thực:

💡 10.1. Stateless by Design¶

• Không lưu token, session hay user state.
• Mọi trạng thái được delegate tới token-service, user-service.
• Có thể scale ngang (horizontal scaling) dễ dàng.

🔄 10.2. Cơ chế Retry & Timeout¶

❗ Mọi retry đều phải gắn trace_id để đảm bảo idempotency và debug chính xác.

🧱 10.3. Fail-Fast Strategy¶

• Nếu bất kỳ service backend nào trả về lỗi không recover được (Google, token, user), Auth Service sẽ trả lỗi ngay lập tức kèm ErrorEnvelope.
• Tránh “hấp hối” nhiều tầng – mọi failure đều rõ ràng.

⛑ 10.4. Graceful Fallback¶

• Nếu audit-service không khả dụng → ghi log audit_event_failed để retry sau (async hoặc batch).
• Nếu user-service mất kết nối → trả lỗi rõ ràng user.sync.failed với chi tiết trong error.details.

🛡 10.5. Circuit Breaker (Tùy chọn)¶

• Có thể bật circuit-breaker bằng fastapi_circuitbreaker hoặc pybreaker cho từng service critical.
• Ví dụ: nếu token-service thất bại > 5 lần liên tục trong 30s → tạm thời ngắt luồng login để giảm tải.

🧪 10.6. Chaos Testing (khuyến nghị)¶

🧮 10.7. SLA gợi ý¶

Dưới đây là nội dung chi tiết cho mục ## 11. ⚡️ Hiệu năng & Scale trong auth-service/master/design.md, tập trung vào đặc thù xử lý nhanh, stateless và khả năng scale ngang dễ dàng:

11. ⚡️ Hiệu năng & Scale¶

auth-service/master là một trong những dịch vụ nhạy cảm nhất về hiệu năng do: - Tham gia trực tiếp vào luồng đăng nhập - Gọi nhiều dịch vụ backend (Google, user, token, audit) - Phải phản hồi gần như real-time

🚀 11.1. Đặc điểm hiệu năng¶

Đây là service lý tưởng để scale theo chiều ngang (horizontal scaling).

🧮 11.2. Ước lượng hiệu năng¶

Trong môi trường production, thời gian xử lý 99 percentile nên dưới 800ms cho full login.

📏 11.3. Benchmark cơ bản (tham khảo)¶

500 concurrent requests
1000 RPS tổng
99.5% success rate
Average latency: ~650ms
Memory usage: ~60MB / instance

📈 11.4. Chiến lược scale¶

📉 11.5. Tối ưu cụ thể¶

Dưới đây là phần ## 12. 🧩 Triển khai & Migration dành cho auth-service/master/design.md, tập trung vào quy trình triển khai an toàn, không downtime và hỗ trợ nâng cấp cấu hình OAuth2 theo tenant.

12. 🧩 Triển khai & Migration¶

🚀 12.1. Chiến lược triển khai¶

auth-service/master được thiết kế để: - Dễ dàng triển khai theo mô hình microservice - Tách biệt rõ môi trường (staging, production) - Hạn chế downtime bằng rolling update

📦 Cách triển khai tiêu chuẩn:¶

⛳ 12.2. Zero Downtime Strategy¶

🔄 12.3. Migration Strategy (Dữ liệu & Cấu hình)¶

✅ Bảng auth_provider_config:¶

• Có thể được khởi tạo qua script SQL hoặc Alembic.
• Hỗ trợ nhiều tenant: mỗi tenant có cấu hình OAuth riêng.

CREATE TABLE auth_provider_config (
    id UUID PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    provider TEXT DEFAULT 'google',
    client_id TEXT NOT NULL,
    client_secret TEXT NOT NULL,
    redirect_uri TEXT NOT NULL,
    scopes TEXT[] DEFAULT ARRAY['email', 'profile'],
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMPTZ DEFAULT now(),
    updated_at TIMESTAMPTZ DEFAULT now()
);

📌 Gợi ý Migration bước đầu:¶

1. Tạo record mặc định cho tenant vas-primary từ file seeds/init_google_oauth.sql
2. Load config OAuth từ bảng khi service start
3. Dùng cache nội bộ để giảm truy vấn DB (TTL 5 phút)

🧪 12.4. Chuẩn bị cho production¶

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

• Interface Contract
• Data Model
• OpenAPI Spec
• ADR-006 - Auth Strategy
• ADR-012 - Response Structure
• ADR-011 - API Error Format