📘 Auth Service Sub – Interface Contract¶

1. 🎯 Mục tiêu & Phạm vi tài liệu¶

Tài liệu này định nghĩa rõ các hợp đồng giao tiếp (interface contract) của auth-service/sub – một service chịu trách nhiệm xác thực người dùng theo từng tenant, bao gồm:

• Đăng nhập qua OTP hoặc tài khoản nội bộ (Local login)
• Quản lý vòng đời phiên đăng nhập (auth_sessions)
• Thu hồi phiên hoặc token đã cấp
• Cung cấp metadata và audit cho các service khác

🎯 Mục tiêu chính¶

• Là cơ sở chính thức cho việc triển khai backend và frontend tích hợp
• Chuẩn hoá request/response theo OpenAPI
• Áp dụng các quy tắc phân quyền và bảo mật theo chuẩn RBAC động
• Làm cơ sở cho contract testing, CI/CD và monitoring

📦 Các API được định nghĩa tại đây¶

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

Các chức năng sau không nằm trong tài liệu này và được định nghĩa ở nơi khác:

🧭 Định hướng kiến trúc¶

Tài liệu này được xây dựng dựa trên nguyên lý:

• Stateless Service: mọi trạng thái phiên đều externalized
• Multi-tenant per-instance: mọi request bắt buộc đi kèm X-Tenant-ID
• RBAC Externalized: mọi permission và điều kiện truy cập được xử lý tại gateway hoặc middleware
• Auditability: mọi hành vi phát sinh đều gửi sự kiện để trace và giám sát

📌 Mọi API trong tài liệu đều đồng bộ 100% với file OpenAPI (openapi.yaml) của auth-service/sub.

2. 🔐 Chính sách Bảo mật & Phân quyền¶

Toàn bộ các endpoint trong auth-service/sub yêu cầu xác thực và phân quyền chặt chẽ dựa trên:

• JWT token được cấp từ token-service
• X-Tenant-ID để định danh tenant hiện hành
• Permission động (RBAC) để giới hạn quyền truy cập theo vai trò và ngữ cảnh

2.1. 🛡 Security Scheme¶

⚠️ Token phải được cấp hợp lệ từ token-service, ký bằng khóa RS256.

2.2. 🧩 Cơ chế kiểm soát phân quyền¶

Hệ thống RBAC theo mô hình permission + condition, được xử lý ngoài service (tại api-gateway hoặc middleware) và được kiểm tra lại trong audit/logic nếu cần.

Ví dụ:¶

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

2.3. 📋 Bảng mapping permission¶

Nếu user không thoả x-condition, hệ thống sẽ trả lỗi 403 Forbidden.

2.4. 🔐 Bảo vệ dữ liệu nhạy cảm¶

• Các trường như ip_address, user_agent, location trong session chỉ trả về nếu có quyền session.read:any
• Với quyền session.read:self, một số trường có thể bị cắt bỏ để bảo vệ quyền riêng tư

2.5. 🧠 Gợi ý triển khai¶

✅ Cơ chế bảo mật và phân quyền được thiết kế để hoạt động an toàn trong môi trường multi-tenant, đồng thời linh hoạt cho quản trị hệ thống trên từng tenant cụ thể.

3. 📌 Tổng quan API & Luồng nghiệp vụ¶

Các API trong auth-service/sub tập trung phục vụ việc xác thực người dùng theo từng tenant. Tất cả đều tuân thủ kiến trúc phân tầng rõ ràng, hoạt động theo luồng chuẩn xác thực – phát token – quản lý session – thu hồi token.

3.1. 🔁 Các nhóm chức năng chính¶

3.2. 🧭 Luồng xử lý chính¶

sequenceDiagram
  participant Frontend
  participant API Gateway
  participant Auth Sub
  participant Token Service
  participant Redis

  Frontend->>+API Gateway: /auth/login (OTP/local)
  API Gateway->>+Auth Sub: chuyển tiếp login
  Auth Sub->>+Token Service: yêu cầu cấp JWT
  Token Service-->>-Auth Sub: access_token + refresh_token
  Auth Sub->>Redis: ghi revoked cache (nếu logout)
  Auth Sub-->>-API Gateway: trả về JWT
  API Gateway-->>-Frontend: JWT

  note over Auth Sub,Redis: Emit: auth.token.issued

3.3. 🌐 Mối liên hệ với các service khác¶

3.4. 📣 Sự kiện được phát ra¶

📌 Luồng nghiệp vụ trong auth-service/sub được thiết kế đơn giản, dễ mở rộng, và phù hợp tuyệt đối với mô hình multi-tenant per-instance của dx-vas.

4. 📬 Chi tiết các Endpoint¶

4.1. POST /auth/login¶

Đây là endpoint chính để xác thực người dùng thông qua OTP hoặc tài khoản nội bộ (local). Sau khi xác thực thành công, hệ thống sẽ tạo session, phát JWT, lưu metadata và phát sự kiện auth.token.issued.

📥 Request¶

Header yêu cầu:

Body (LoginRequest, dùng discriminator login_type):

{
  "login_type": "otp",  // hoặc "local"
  "phone_number": "+84901234567", // OTP
  "otp_code": "123456"
}

Hoặc:

{
  "login_type": "local",
  "username": "admin",
  "password": "123456"
}

Các field cụ thể phụ thuộc vào login_type. Tài liệu schemas/LoginRequest sẽ định nghĩa cụ thể.

📤 Response¶

{
  "meta": {
    "request_id": "xyz",
    "timestamp": "..."
  },
  "data": {
    "access_token": "<JWT>",
    "refresh_token": "<JWT>",
    "expires_in": 3600,
    "session_id": "f2b9c6ae-...95c",
    "token_type": "Bearer"
  }
}

• Response luôn bọc trong ResponseMeta + TokenEnvelope
• session_id là UUID phiên login được lưu trong auth_sessions
• Token được phát từ token-service, không phải nội bộ auth-sub

🔐 Phân quyền & Điều kiện¶

📣 Sự kiện phát ra¶

• auth.token.issued
• Payload gồm: user_id, tenant_id, auth_method, session_id, ip_address, user_agent, device_type, location

❌ Mã lỗi có thể trả về¶

🧪 Gợi ý kiểm thử¶

• Đăng nhập đúng/sai OTP
• Đăng nhập local đúng/sai
• Thiếu X-Tenant-ID → lỗi
• Session phải được ghi vào bảng auth_sessions
• Token phải có claim đúng (sub, session_id, tenant_id, exp...)

📌 Đây là endpoint duy nhất tạo JWT trong auth-service/sub. Mọi cấp phát token đều được uỷ quyền sang token-service.

4.2. POST /auth/logout¶

Endpoint này cho phép người dùng hoặc hệ thống thu hồi token hiện tại (access hoặc refresh) và đánh dấu session tương ứng là đã bị huỷ. Đồng thời phát sự kiện auth.token.revoked để các service khác cập nhật trạng thái.

📥 Request¶

Header yêu cầu:

Body (LogoutRequest, optional):

{
  "reason": "user_logout"
}

Nếu không truyền reason, mặc định là "user_logout".

📤 Response¶

{
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  },
  "data": {
    "success": true
  }
}

• Trả về 200 OK với success flag
• Không cần trả lại token

🔐 Phân quyền & Điều kiện¶

🧩 Hành vi nội bộ¶

• Token hiện tại được decode → lấy jti (JWT ID), session_id, user_id
• Tạo key revoked:<jti> trong Redis với TTL đúng bằng thời gian còn lại
• Cập nhật bản ghi auth_sessions tương ứng: revoked_at, revoked_reason
• Ghi log audit và phát sự kiện auth.token.revoked

📣 Sự kiện phát ra¶

• auth.token.revoked
• Payload gồm: session_id, user_id, tenant_id, revoked_reason, revoked_at, ip_address, device_type

❌ Mã lỗi có thể trả về¶

🧪 Gợi ý kiểm thử¶

• Logout access token đang dùng → Redis có key revoked:<jti>
• Logout refresh token → cũng phải bị revoke
• Check Redis TTL và dữ liệu
• Truy vấn GET /auth/sessions → session đổi trạng thái
• Replay token sau logout → phải bị từ chối tại Gateway

📌 Đây là cơ chế chính để thực hiện session termination chủ động, phục vụ cả frontend và admin console. Các revoke xảy ra tại đây là soft revoke (qua Redis), không xóa token vật lý.

4.3. GET /auth/sessions¶

Endpoint này cho phép người dùng truy vấn danh sách phiên đăng nhập trước đó của chính mình, hoặc truy xuất của người dùng khác (nếu có quyền). Hỗ trợ lọc theo user_id, trạng thái, phân trang.

📥 Request¶

Header yêu cầu:

Query Parameters (tùy chọn):

📤 Response¶

{
  "meta": {
    "request_id": "...",
    "pagination": {
      "total": 82,
      "limit": 20,
      "offset": 0
    }
  },
  "data": [
    {
      "session_id": "f2b9c6ae-...",
      "user_id": "de56...",
      "auth_method": "otp",
      "created_at": "2024-06-01T10:45:00Z",
      "revoked_at": null,
      "ip_address": "203.113.12.1",
      "device_type": "web",
      "user_agent": "Mozilla/5.0 ...",
      "location": "Ho Chi Minh, VN",
      "status": "active"
    }
  ]
}

• Trả về mảng SessionOut theo chuẩn schema
• Metadata gồm pagination info và request_id

🔐 Phân quyền & Điều kiện¶

Nếu user gửi user_id ≠ chính họ → cần session.read:any.

🔎 Lưu ý về bảo mật¶

• Nếu chỉ có read:self, hệ thống sẽ ẩn hoặc mask một số metadata (ip_address, location, user_agent)
• Nếu có read:any, sẽ thấy đầy đủ thông tin các session

❌ Mã lỗi có thể trả về¶

🧪 Gợi ý kiểm thử¶

• Gọi không truyền user_id → trả session chính mình
• Gọi user_id = self nhưng thiếu quyền → 403
• Phân trang: limit/offset hoạt động chính xác
• So sánh số lượng session khớp DB auth_sessions
• Mask metadata khi dùng quyền read:self

📌 Đây là API quan trọng để người dùng tự kiểm tra lịch sử hoạt động hoặc để quản trị viên giám sát đăng nhập trong tenant của họ.

4.4. POST /auth/sessions/{id}/revoke¶

Endpoint này cho phép quản trị viên thu hồi một phiên đăng nhập cụ thể của người dùng trong tenant. Hành động này vô hiệu hóa token tương ứng nếu còn hiệu lực, cập nhật trạng thái session và phát sự kiện auth.token.revoked.

📥 Request¶

Header yêu cầu:

Path Parameter:

Body (RevokeSessionRequest, optional):

{
  "reason": "admin_forced"
}

Nếu không cung cấp reason, hệ thống dùng mặc định "manual".

📤 Response¶

{
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  },
  "data": {
    "success": true
  }
}

• Trả về 200 OK nếu thu hồi thành công hoặc đã bị thu hồi trước đó

🔐 Phân quyền & Điều kiện¶

Chỉ cho phép thao tác với các session thuộc tenant hiện tại.

🧩 Hành vi nội bộ¶

• Truy vấn auth_sessions để xác định session hợp lệ
• Nếu session đã bị revoke → trả success idempotent
• Nếu session còn hoạt động:
• Ghi revoked_at, revoked_reason
• Ghi Redis key revoked:<jti> nếu token còn hiệu lực
• Emit sự kiện auth.token.revoked

📣 Sự kiện phát ra¶

• auth.token.revoked
• Payload gồm: session_id, user_id, tenant_id, revoked_reason, revoked_by, ip_address

❌ Mã lỗi có thể trả về¶

🧪 Gợi ý kiểm thử¶

• Revoke một session chưa bị thu hồi → cập nhật DB, Redis
• Revoke lại cùng session → không lỗi (idempotent)
• Truy vấn GET /auth/sessions → thấy trạng thái revoked
• Xác minh sự kiện auth.token.revoked được phát đúng metadata
• Check token tương ứng → bị từ chối khi dùng lại

📌 Đây là API quản trị quan trọng cho phép vô hiệu hóa các phiên nghi ngờ hoặc chấm dứt truy cập ngay lập tức trong các tình huống khẩn cấp về bảo mật.

5. 📦 Schema sử dụng trong request/response¶

Tài liệu này mô tả các schema dữ liệu chính được sử dụng trong body của các request và response của auth-service/sub. Tất cả schema đều được định nghĩa và version hóa rõ ràng trong file OpenAPI (openapi.yaml) đi kèm.

5.1. 📨 LoginRequest¶

{
  "login_type": "otp",  // hoặc "local"
  "phone_number": "+84901234567",
  "otp_code": "123456"
}

• login_type: enum (otp, local)
• Nếu otp → yêu cầu phone_number và otp_code
• Nếu local → yêu cầu username và password
• Được định nghĩa bằng oneOf trong OpenAPI với discriminator login_type

5.2. 📤 TokenEnvelope¶

{
  "access_token": "eyJhbGciOiJSUzI1NiIsIn...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsIn...",
  "expires_in": 3600,
  "session_id": "3b61237d-...",
  "token_type": "Bearer"
}

• Bao gói thông tin token được cấp
• Trả về trong mọi response login

5.3. 📥 LogoutRequest¶

{
  "reason": "user_logout"
}

• reason: string, optional, các giá trị gợi ý: user_logout, expired, device_lost, admin_forced

5.4. 📜 SessionOut¶

{
  "session_id": "b6a1d437-...",
  "user_id": "1e332...",
  "auth_method": "local",
  "created_at": "2024-06-01T10:45:00Z",
  "revoked_at": null,
  "ip_address": "192.168.1.1",
  "device_type": "web",
  "user_agent": "Mozilla/5.0 ...",
  "location": "Ho Chi Minh, VN",
  "status": "active"
}

• Trả về trong GET /auth/sessions
• Có thể bị ẩn/mask bớt nếu quyền chỉ là session.read:self

5.5. 🛑 ErrorEnvelope¶

{
  "error": {
    "code": "auth.invalid_credentials",
    "message": "Tên đăng nhập hoặc mật khẩu không đúng",
    "data": {
      "attempts_left": 1
    }
  },
  "meta": {
    "request_id": "xyz",
    "timestamp": "2024-06-13T07:22:30Z"
  }
}

• Được chuẩn hóa theo adr-011-api-error-format.md
• Tất cả response lỗi đều bọc trong ErrorEnvelope

5.6. 📦 ResponseMeta¶

{
  "request_id": "req_abc123",
  "timestamp": "2024-06-13T07:22:30Z",
  "pagination": {
    "total": 120,
    "limit": 20,
    "offset": 0
  }
}

• Có mặt trong mọi response thành công
• pagination chỉ có khi dùng response dạng danh sách

📌 Tất cả schema đều versioned và test tự động bằng contract testing tools (schemathesis, dredd, etc.) trong CI pipeline.

6. 🎯 Quy ước response & mã lỗi¶

Mọi API trong auth-service/sub tuân thủ nghiêm ngặt định dạng phản hồi chuẩn hoá của hệ thống VAS DX. Điều này đảm bảo tính nhất quán, dễ debug và khả năng mở rộng các công cụ tự động hoá (contract testing, monitoring, tracing).

6.1. 📦 Cấu trúc phản hồi thành công¶

Mỗi response thành công đều phải bọc trong:

{
  "meta": {
    "request_id": "abc123",
    "timestamp": "2024-06-13T08:00:00Z"
  },
  "data": {
    // Nội dung tuỳ API
  }
}

• meta: luôn có request_id (traceable), timestamp, và optional pagination
• data: chứa payload thực tế (token, session list, success flag...)

Cấu trúc này được chuẩn hóa theo adr-012-response-structure.md

6.2. 🛑 Cấu trúc phản hồi lỗi¶

Tất cả lỗi đều trả về định dạng chuẩn ErrorEnvelope:

{
  "error": {
    "code": "auth.invalid_credentials",
    "message": "Sai tên đăng nhập hoặc mật khẩu",
    "data": {
      "attempts_left": 1
    }
  },
  "meta": {
    "request_id": "abc123",
    "timestamp": "2024-06-13T08:01:30Z"
  }
}

• code: mã lỗi dạng snake-case (bắt buộc)
• message: mô tả ngắn gọn, có thể dùng đa ngôn ngữ
• data: optional – dùng để truyền thêm context (ví dụ: attempts_left, lockout_duration)

6.3. 📋 Danh sách mã lỗi phổ biến¶

Danh sách đầy đủ được định nghĩa trong file error-codes.md và adr-011-api-error-format.md

6.4. 🧪 Contract testing yêu cầu¶

• Mỗi mã lỗi đều phải có test tương ứng
• Hành vi sai phải trả đúng mã HTTP + error.code
• CI pipeline không cho phép thay đổi error.code hoặc ResponseMeta format nếu không có migration

✅ Cách tiếp cận nhất quán giúp tăng khả năng giám sát tự động, phân tích lỗi chính xác, hỗ trợ frontend hiển thị rõ ràng và giảm thiểu lỗi tích hợp giữa các đội.

7. 🧪 Hỗ trợ kiểm thử & tích hợp¶

Tài liệu này hỗ trợ đầy đủ cho các hoạt động kiểm thử thủ công, kiểm thử tự động, tích hợp CI/CD và contract testing nhằm đảm bảo độ tin cậy và tính đúng đắn của auth-service/sub.

7.1. ✅ Mẫu request thực tế¶

📎 Gợi ý: Sử dụng [Postman Collection] hoặc [Insomnia Export] đính kèm dự án.

7.2. 🧪 Contract Testing¶

✅ Tài liệu này đồng bộ 100% với openapi.yaml – có thể dùng để sinh test auto.

7.3. 🧪 Kiểm thử phân quyền & điều kiện¶

• Test thiếu X-Tenant-ID → trả lỗi 400
• Test session.read:self vs read:any → khác nhau về metadata
• Test session.revoke:any → không được phép thu hồi phiên tenant khác
• Test auth.token.revoked → emit event đúng metadata

7.4. 🛠 Tích hợp CI/CD¶

• Mỗi PR bắt buộc chạy test schema → không cho phép thay đổi ErrorEnvelope, ResponseMeta
• Có rule YAML kiểm tra presence của x-required-permission, x-condition trong mỗi path

7.5. 📡 Tích hợp observability¶

• Mỗi request được gán request_id và trace ID để debug xuyên service
• Response chuẩn hóa hỗ trợ APM/monitoring như Datadog, Grafana Tempo, OpenTelemetry

✅ Với tài liệu này, đội frontend, backend, QA, và devops đều có thể tự động hoá quá trình kiểm thử và kiểm tra hợp đồng tích hợp xuyên tầng một cách chính xác và hiệu quả.

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

• Data Model
• OpenAPI Spec
• Design