pos-system/services/iam-service-net/docs/vi/ARCHITECTURE.md

Kiến Trúc IAM Service

Tài liệu kiến trúc cho IAM Service (Quản lý Danh tính và Truy cập) xây dựng với .NET 10, OpenIddict, và Clean Architecture.

Tổng Quan Kiến Trúc

graph TB
    subgraph "Clients"
        WEB[Web App]
        MOB[Mobile App]
        SVC[Các Services khác]
    end
    
    subgraph "Lớp API"
        AUTH[AuthController]
        USR[UsersController]
        TOK[Token Endpoint]
    end
    
    subgraph "Lớp Application - CQRS"
        CMD[Commands]
        QRY[Queries]
        VAL[Validators]
        BHV[Behaviors]
    end
    
    subgraph "Lớp Domain"
        USER[User Aggregate]
        ROLE[Role Aggregate]
        EVT[Domain Events]
    end
    
    subgraph "Infrastructure"
        CTX[Identity DbContext]
        REPO[Repositories]
        OIDDICT[OpenIddict]
    end
    
    subgraph "External"
        DB[(PostgreSQL)]
        REDIS[(Redis)]
    end
    
    WEB --> AUTH
    MOB --> AUTH
    SVC --> TOK
    AUTH --> CMD
    AUTH --> QRY
    USR --> CMD
    USR --> QRY
    TOK --> OIDDICT
    CMD --> VAL
    CMD --> BHV
    CMD --> USER
    QRY --> REPO
    USER --> EVT
    REPO --> CTX
    OIDDICT --> CTX
    CTX --> DB
    CTX --> REDIS
    
    style AUTH fill:#4a90d9,stroke:#2d5986,color:#fff
    style USER fill:#50c878,stroke:#2d8659,color:#fff
    style DB fill:#ff6b6b,stroke:#c0392b,color:#fff
    style OIDDICT fill:#9b59b6,stroke:#7d3c98,color:#fff

Luồng Xác Thực OAuth2

sequenceDiagram
    participant Client
    participant AuthController
    participant OpenIddict
    participant UserManager
    participant Database
    
    Note over Client,Database: Password Grant Flow (Đăng nhập)
    
    Client->>AuthController: POST /connect/token<br/>grant_type=password
    AuthController->>OpenIddict: Validate Request
    OpenIddict->>UserManager: FindByEmailAsync()
    UserManager->>Database: Query User
    Database-->>UserManager: User Data
    UserManager->>UserManager: CheckPasswordAsync()
    UserManager-->>OpenIddict: User Validated
    OpenIddict->>OpenIddict: Tạo Tokens (JWT)
    OpenIddict-->>AuthController: Token Response
    AuthController-->>Client: access_token + refresh_token
    
    Note over Client,Database: Sử dụng Access Token
    
    Client->>AuthController: GET /api/v1/users/me<br/>Authorization: Bearer {token}
    AuthController->>OpenIddict: Validate JWT
    OpenIddict-->>AuthController: Claims Principal
    AuthController-->>Client: User Data

Các Loại Token và Grant Types

graph LR
    subgraph "Grant Types"
        PWD[Password Grant]
        REF[Refresh Token]
        CC[Client Credentials]
    end
    
    subgraph "Tokens"
        AT[Access Token<br/>15 phút]
        RT[Refresh Token<br/>7 ngày]
    end
    
    subgraph "Use Cases"
        USER[Đăng nhập User]
        RENEW[Làm mới Token]
        S2S[Service-to-Service]
    end
    
    PWD --> AT
    PWD --> RT
    REF --> AT
    CC --> AT
    
    USER --> PWD
    RENEW --> REF
    S2S --> CC
    
    style AT fill:#2ecc71,stroke:#27ae60,color:#fff
    style RT fill:#f39c12,stroke:#d68910,color:#fff
    style CC fill:#9b59b6,stroke:#7d3c98,color:#fff

Domain Model

User Aggregate

classDiagram
    class ApplicationUser {
        +Guid Id
        +string Email
        +string FirstName
        +string LastName
        +UserStatus Status
        +DateTime CreatedAt
        +DateTime? LastLoginAt
        +UpdateProfile(firstName, lastName)
        +Disable()
        +RecordLogin()
    }
    
    class UserStatus {
        <<enumeration>>
        +Active
        +Locked
        +Disabled
        +PendingVerification
    }
    
    class ApplicationRole {
        +Guid Id
        +string Name
        +string Description
    }
    
    ApplicationUser --> UserStatus : có
    ApplicationUser "nhiều" --> "nhiều" ApplicationRole : thuộc về

Database Schema

erDiagram
    AspNetUsers {
        uuid Id PK
        string Email UK
        string PasswordHash
        string FirstName
        string LastName
        int StatusId FK
        datetime CreatedAt
        datetime LastLoginAt
    }
    
    UserStatuses {
        int Id PK
        string Name
    }
    
    AspNetRoles {
        uuid Id PK
        string Name UK
        string Description
    }
    
    AspNetUserRoles {
        uuid UserId PK,FK
        uuid RoleId PK,FK
    }
    
    OpenIddictTokens {
        uuid Id PK
        uuid ApplicationId FK
        uuid AuthorizationId FK
        string Type
        string Status
        datetime ExpirationDate
    }
    
    AspNetUsers ||--o{ UserStatuses : có
    AspNetUsers ||--o{ AspNetUserRoles : có
    AspNetRoles ||--o{ AspNetUserRoles : có

CQRS Pipeline

sequenceDiagram
    participant Controller
    participant MediatR
    participant LoggingBehavior
    participant ValidatorBehavior
    participant TransactionBehavior
    participant CommandHandler
    participant Repository
    
    Controller->>MediatR: Send(Command)
    MediatR->>LoggingBehavior: Handle
    LoggingBehavior->>ValidatorBehavior: Next()
    ValidatorBehavior->>TransactionBehavior: Next()
    TransactionBehavior->>CommandHandler: Next()
    CommandHandler->>Repository: Save
    Repository-->>CommandHandler: Result
    CommandHandler-->>Controller: Response

Thứ Tự Pipeline Behaviors

Thứ tự	Behavior	Mục đích
1	LoggingBehavior	Ghi log request/response với timing
2	ValidatorBehavior	FluentValidation
3	TransactionBehavior	Bao database transaction

Kiến Trúc Bảo Mật

graph TD
    subgraph "Authentication"
        JWT[JWT Bearer Tokens]
        RS256[RS256 Signing]
        OIDC[OpenIddict Server]
    end
    
    subgraph "Authorization"
        RBAC[Role-Based Access]
        CLAIMS[Claims-Based]
        POLICY[Policy Enforcement]
    end
    
    subgraph "Protection"
        HASH[bcrypt Password Hash]
        HTTPS[HTTPS/TLS]
        CORS[CORS Policy]
    end
    
    JWT --> RS256
    RS256 --> OIDC
    RBAC --> CLAIMS
    CLAIMS --> POLICY
    
    style JWT fill:#3498db,stroke:#2980b9,color:#fff
    style RBAC fill:#e74c3c,stroke:#c0392b,color:#fff
    style HASH fill:#2ecc71,stroke:#27ae60,color:#fff

Health Checks

graph TD
    HC[Health Check Endpoints]
    HC -->|/health/live| L[Liveness Probe]
    HC -->|/health/ready| R[Readiness Probe]
    HC -->|/health| F[Full Status]
    
    R --> PG[(PostgreSQL Check)]
    R --> RD[(Redis Check)]
    
    style HC fill:#3498db,stroke:#2980b9,color:#fff
    style L fill:#2ecc71,stroke:#27ae60,color:#fff
    style R fill:#f39c12,stroke:#d68910,color:#fff

Kiến Trúc Deployment

Docker Compose (Local/Development)

services:
  iam-service:
    build: .
    ports: ["5001:8080"]
    depends_on:
      - postgres
      - redis
    environment:
      - DATABASE_URL=Host=postgres;...
      
  postgres:
    image: postgres:16-alpine
    
  redis:
    image: redis:7-alpine

Kubernetes (Production)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: iam-service
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: iam-service
        image: goodgo/iam-service:latest
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080

Xử Lý Lỗi

Phân Cấp Exception

Exception
└── DomainException
    └── (Custom domain exceptions)

Problem Details (RFC 7807)

Tất cả lỗi trả về định dạng Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Lỗi Validation",
  "status": 400,
  "detail": "Một hoặc nhiều lỗi validation đã xảy ra.",
  "errors": {
    "Email": ["Email là bắt buộc"]
  }
}

Cân Nhắc Hiệu Năng

1. Connection Pooling: EF Core với Npgsql resilience
2. Token Caching: Redis cho token validation
3. Async Operations: Tất cả I/O operations đều async
4. Database Indexes: Cấu hình trong EntityConfigurations

Tài Liệu Tham Khảo

• OpenIddict Documentation
• ASP.NET Core Identity
• OAuth2 Specification
• eShopOnContainers
• CQRS Pattern