pos-system/docs/vi/architecture/iam-proposal.md

# Đề Xuất Kiến Trúc IAM Service

Tài liệu này mô tả đề xuất kiến trúc cho IAM Service (Identity and Access Management Service), mở rộng từ auth-service hiện tại.

## Tổng Quan: Auth Service → IAM Service

**IAM Service** cung cấp:
- **OAuth2/OpenID Connect** với Duende IdentityServer
- **ASP.NET Core Identity** cho user management
- **Role-Based Access Control (RBAC)**
- **JWT Tokens** (Access 15min, Refresh 7 days, RS256 signing)
- **2FA/MFA Support** (TOTP với QR Code và Recovery Codes)
- **Email Verification** (Xác thực email qua SMTP)
- **Social Login** (Google, Facebook OAuth)
- **Distributed Caching** (Redis với ICacheService)

> [!NOTE]
> IAM Service đã được triển khai với .NET 10, Clean Architecture, Duende IdentityServer tại `services/iam-service-net/`

---

## 1. Phạm Vi IAM Service

### 1.1 Identity Management (Quản Lý Danh Tính)

#### A. User Lifecycle Management
- User CRUD operations
- User provisioning/deprovisioning workflows
- Bulk user operations (import/export)
- User deactivation/reactivation với approval workflow
- Account merging/deduplication
- User archival (soft delete với retention policy)

#### B. Profile Management
- Extended attributes (custom fields)
- Profile picture upload & management
- Contact information (phone, address)
- Preferences & settings
- Profile versioning/audit trail

#### C. Identity Verification
- Email verification
- Phone/SMS verification
- Identity document verification (KYC)
- Multi-level verification (verified, pending, rejected)

#### D. Organizations & Groups
- Organization management (multi-tenant)
- Group/Team management
- Organization hierarchy
- Group-based access control
- Organization-level policies

### 1.2 Access Management (Quản Lý Truy Cập)

#### A. Advanced Access Control
- Just-In-Time (JIT) access provisioning
- Privileged Access Management (PAM)
- Temporary access grants
- Access request/approval workflows
- Delegation & impersonation (admin view)
- Conditional access policies (location, time, device)

#### B. Access Reviews & Certifications
- Periodic access reviews
- Access certification campaigns
- Access analytics & reporting
- Risk scoring for access decisions
- Anomaly detection (unusual access patterns)

### 1.3 Governance & Compliance (Quản Trị & Tuân Thủ)

#### A. Audit & Logging
- Compliance reporting (GDPR, SOC2, ISO 27001)
- Data retention policies
- Audit log search & analytics
- Export audit logs

#### B. Policy Governance
- Policy versioning & rollback
- Policy templates library
- Policy testing & validation
- Policy compliance checks

#### C. Risk Management
- Risk scoring engine
- Risk-based authentication
- Threat detection
- Incident response workflows
- Security posture dashboard

---

## 2. Kiến Trúc Module Structure (Thực Tế)

```
services/iam-service-net/
├── src/
│   ├── IamService.API/              # Presentation Layer
│   │   ├── Controllers/              # AuthController, UsersController, RolesController
│   │   ├── Application/              # CQRS Commands, Queries, Handlers
│   │   │   ├── Commands/             # RegisterUserCommand, ChangePasswordCommand
│   │   │   ├── Queries/              # GetUserQuery, GetUsersQuery
│   │   │   └── Validators/           # FluentValidation validators
│   │   └── Program.cs                # App entry point
│   ├── IamService.Domain/           # Domain Layer
│   │   ├── AggregatesModel/          # ApplicationUser, ApplicationRole
│   │   ├── Events/                   # UserCreatedEvent, UserDeletedEvent
│   │   ├── Exceptions/               # UserNotFoundException, InvalidCredentialsException
│   │   └── SeedWork/                 # Entity, IAggregateRoot, IRepository
│   └── IamService.Infrastructure/   # Infrastructure Layer
│       ├── IamServiceContext.cs      # DbContext with Identity + OpenIddict
│       ├── Repositories/             # UserRepository, RoleRepository
│       └── Services/                 # EmailService, TokenService
├── tests/
│   ├── IamService.UnitTests/
│   └── IamService.FunctionalTests/
├── docs/
├── Dockerfile
└── IamService.slnx
```

### Sơ Đồ Kiến Trúc Clean Architecture

```mermaid
graph TD
    %% Styling Configuration
    classDef base fill:#202020,stroke:#505050,color:#fff,stroke-width:1px;
    classDef core fill:#1a237e,stroke:#3949ab,color:#fff,stroke-width:1px;
    classDef newModule fill:#1b5e20,stroke:#43a047,color:#fff,stroke-width:1px;
    classDef database fill:#4a148c,stroke:#7b1fa2,color:#fff,stroke-width:1px;

    %% Main Service Node
    IAM[IAM Service]:::core

    %% Identity Management Subgraph
    subgraph Identity [Identity Management]
        direction TB
        User[User Lifecycle]:::newModule
        Profile[Profile Mgmt]:::newModule
        Verify[Verification]:::newModule
        Org[Org & Groups]:::newModule
    end

    %% Access Management Subgraph
    subgraph Access [Access Management]
        direction TB
        Req[Access Requests]:::newModule
        Review[Access Reviews]:::newModule
        PAM[PAM]:::newModule
        Analytics[Analytics]:::newModule
    end

    %% Governance Subgraph
    subgraph Governance [Governance & Compliance]
        direction TB
        Comp[Compliance]:::newModule
        Policy[Policy Gov]:::newModule
        Risk[Risk Mgmt]:::newModule
    end

    %% Database
    DB[(Neon Database)]:::database

    %% Relationships
    IAM --> Identity
    IAM --> Access
    IAM --> Governance

    Identity -.-> DB
    Access -.-> DB
    Governance -.-> DB

    %% Internal Dependencies
    Access --> Identity
    Governance ---> Access
```
---

## 3. Database Schema Mở Rộng

### 3.1 Identity Management Models

- **Organization**: Quản lý tổ chức với hierarchy
- **Group**: Quản lý nhóm trong organization
- **GroupMember**: Thành viên của group
- **GroupPermission**: Permissions cho group
- **UserProfile**: Thông tin profile mở rộng của user
- **IdentityVerification**: Xác thực danh tính (email, phone, document)

### 3.2 Access Management Models

- **AccessRequest**: Yêu cầu truy cập
- **AccessRequestApprover**: Người phê duyệt request
- **AccessReview**: Đánh giá truy cập định kỳ
- **AccessReviewItem**: Item trong review

### 3.3 Governance Models

- **ComplianceReport**: Báo cáo tuân thủ (GDPR, SOC2, ISO27001)
- **PolicyTemplate**: Template cho policies
- **RiskScore**: Điểm rủi ro của user

---

## 4. API Endpoints (Thực Tế)

### 4.1 Authentication APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/auth/register` | Đăng ký user mới | ❌ |
| `POST` | `/connect/token` | OAuth2 token endpoint (login, refresh) | ❌ |
| `POST` | `/api/v1/auth/change-password` | Đổi mật khẩu | ✅ |
| `POST` | `/api/v1/auth/logout` | Đăng xuất (revoke tokens) | ✅ |

### 4.2 Email Verification APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/auth/send-verification-email` | Gửi email xác thực | ✅ |
| `POST` | `/api/v1/auth/confirm-email` | Xác nhận email với token | ❌ |

### 4.3 Xác Thực Hai Yếu Tố (2FA) APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/auth/2fa/enable` | Bật 2FA (lấy QR code + recovery codes) | ✅ |
| `POST` | `/api/v1/auth/2fa/verify` | Xác minh mã TOTP & kích hoạt | ✅ |
| `POST` | `/api/v1/auth/2fa/disable` | Tắt 2FA | ✅ |

### 4.4 Social Login APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/auth/external-login/{provider}` | Bắt đầu OAuth flow (Google/Facebook) | ❌ |
| `GET` | `/api/v1/auth/external-callback` | Xử lý OAuth callback | ❌ |
| `GET` | `/api/v1/auth/linked-accounts` | Lấy danh sách providers đã liên kết | ✅ |

### 4.5 User Management APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/users` | Danh sách users (paginated) | ✅ |
| `GET` | `/api/v1/users/me` | Thông tin user hiện tại | ✅ |
| `GET` | `/api/v1/users/{id}` | Lấy user theo ID | ✅ |
| `PUT` | `/api/v1/users/{id}` | Cập nhật user | ✅ |
| `DELETE` | `/api/v1/users/{id}` | Xóa user (soft delete) | ✅ |

### 4.6 Role Management APIs

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/roles` | Danh sách roles | ✅ |
| `POST` | `/api/v1/roles` | Tạo role mới | ✅ Admin |
| `PUT` | `/api/v1/roles/{id}` | Cập nhật role | ✅ Admin |
| `DELETE` | `/api/v1/roles/{id}` | Xóa role | ✅ Admin |

### 4.7 Organization & Group APIs ✅ (New in Phase 2)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/organizations/{id}` | Lấy tổ chức theo ID | ✅ |
| `GET` | `/api/v1/organizations/slug/{slug}` | Lấy tổ chức theo slug | ✅ |
| `POST` | `/api/v1/organizations` | Tạo tổ chức mới | ✅ |
| `PUT` | `/api/v1/organizations/{id}` | Cập nhật tổ chức | ✅ |
| `DELETE` | `/api/v1/organizations/{id}` | Lưu trữ (archive) tổ chức | ✅ |
| `GET` | `/api/v1/organizations/{id}/hierarchy` | Lấy phân cấp tổ chức | ✅ |
| `GET` | `/api/v1/organizations/{id}/children` | Lấy tổ chức con | ✅ |
| `GET` | `/api/v1/groups` | Danh sách groups theo organizationId | ✅ |
| `GET` | `/api/v1/groups/{id}` | Lấy group theo ID | ✅ |
| `POST` | `/api/v1/groups` | Tạo group mới | ✅ |
| `DELETE` | `/api/v1/groups/{id}` | Xóa group (soft delete) | ✅ |
| `POST` | `/api/v1/groups/{id}/members` | Thêm thành viên vào group | ✅ |
| `DELETE` | `/api/v1/groups/{id}/members/{userId}` | Xóa thành viên khỏi group | ✅ |

### 4.8 User Profile APIs ✅ (New in Phase 2)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/users/{id}/profile` | Lấy profile user | ✅ |
| `PUT` | `/api/v1/users/{id}/profile` | Cập nhật profile user | ✅ |
| `PUT` | `/api/v1/users/{id}/profile/attributes/{key}` | Đặt profile attribute | ✅ |

### 4.9 Identity Verification APIs ✅ (New in Phase 2)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/verifications/phone` | Yêu cầu xác thực số điện thoại | ✅ |
| `POST` | `/api/v1/verifications/email` | Yêu cầu xác thực email | ✅ |
| `POST` | `/api/v1/verifications/{id}/confirm` | Xác nhận với OTP code | ✅ |

### 4.10 Access Requests APIs ✅ (New in Phase 3A)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/access-requests` | Tạo yêu cầu truy cập mới | ✅ |
| `GET` | `/api/v1/access-requests` | Lấy danh sách requests của user | ✅ |
| `GET` | `/api/v1/access-requests/{id}` | Lấy request theo ID | ✅ |
| `POST` | `/api/v1/access-requests/{id}/submit` | Submit request để phê duyệt | ✅ |
| `POST` | `/api/v1/access-requests/{id}/approve` | Phê duyệt request | ✅ |
| `POST` | `/api/v1/access-requests/{id}/reject` | Từ chối request | ✅ |
| `DELETE` | `/api/v1/access-requests/{id}` | Hủy request | ✅ |
| `GET` | `/api/v1/access-requests/pending` | Lấy requests đang chờ phê duyệt | ✅ |

### 4.11 Access Reviews APIs ✅ (New in Phase 3B)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/access-reviews` | Tạo access review mới | ✅ |
| `GET` | `/api/v1/access-reviews/{id}` | Lấy review theo ID | ✅ |
| `POST` | `/api/v1/access-reviews/{id}/items` | Thêm item vào review | ✅ |
| `POST` | `/api/v1/access-reviews/{id}/start` | Bắt đầu review campaign | ✅ |
| `POST` | `/api/v1/access-reviews/{id}/items/{itemId}/review` | Certify/Revoke item | ✅ |
| `POST` | `/api/v1/access-reviews/{id}/complete` | Hoàn thành review | ✅ |

### 4.12 Privileged Access Management (PAM) APIs ✅ (New in Phase 3B)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/privileged-access/request` | Yêu cầu JIT elevated access | ✅ |
| `GET` | `/api/v1/privileged-access/active` | Lấy grants đang active | ✅ |
| `POST` | `/api/v1/privileged-access/{id}/revoke` | Thu hồi privileged access | ✅ |

### 4.13 Audit Log APIs ✅ (New in Phase 4A)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/audit/logs` | Lấy audit logs (filtered, paginated) | ✅ |

### 4.14 Compliance APIs ✅ (New in Phase 4A)

| Method | Endpoint | Mô tả | Auth |
|--------|----------|-------|------|
| `POST` | `/api/v1/compliance/reports` | Tạo compliance report mới | ✅ |
| `GET` | `/api/v1/compliance/reports` | Lấy danh sách reports | ✅ |
| `GET` | `/api/v1/compliance/reports/{id}` | Lấy report chi tiết | ✅ |
| `POST` | `/api/v1/compliance/reports/{id}/complete` | Hoàn thành report | ✅ |
| `GET` | `/api/v1/compliance/violations` | Lấy violations chưa giải quyết | ✅ |

### 4.15 Governance APIs (Planned - Phase 4B)

> [!NOTE]
> Các APIs dưới đây là tính năng **đang được lên kế hoạch** cho Phase 4B.

```
# Policy Governance
GET    /api/v1/policies
POST   /api/v1/policies
GET    /api/v1/policies/:id/versions
POST   /api/v1/policies/:id/activate

# Risk Management
GET    /api/v1/risk/scores/:userId
POST   /api/v1/risk/calculate

# Security Dashboard
GET    /api/v1/dashboard/security
```

---

## 5. Implementation Roadmap

### Phase 1: Foundation ✅ (Completed)
- ✅ Migrate từ auth-service sang iam-service (.NET 10 + Duende IdentityServer)
- ✅ CQRS với MediatR Pattern
- ✅ User Registration, Login, Logout
- ✅ Password Management (change-password)
- ✅ User Management APIs (CRUD)
- ✅ Role Management APIs

### Phase 1.5: Enhanced Security ✅ (Completed)
- ✅ Email Verification (send + confirm)
- ✅ 2FA/MFA với TOTP (QR Code, Recovery Codes)
- ✅ Social Login (Google, Facebook OAuth)
- ✅ Distributed Caching với Redis (ICacheService)
- ✅ Token Blacklisting cho logout

### Phase 2: Identity Management ✅ (Completed)
- ✅ User lifecycle management
- ✅ Identity verification (phone, email)
- ✅ Organization & Group management
- ✅ Profile management with extended attributes (ProfileAttribute entity)

### Phase 3: Access Management ✅ (Completed)
- ✅ Access request/approval workflows (Create → Submit → Approve/Reject)
- ✅ Access review & certification system (Certify/Revoke decisions)
- ✅ Privileged Access Management (PAM) với JIT elevated access
- ✅ Entity configurations với EF Core Value Conversion

### Phase 4: Governance (In Progress)

#### Phase 4A: Audit & Compliance ✅ (Completed)
- ✅ `AuditLog` aggregate với 18 event types
- ✅ `ComplianceReport` aggregate (GDPR, SOC2, ISO27001, HIPAA)
- ✅ Audit log search & filtering
- ✅ Compliance report generation & violations tracking

#### Phase 4B: Policy & Risk (Planned)
- 🔄 PolicyTemplate aggregate với versioning
- 🔄 RiskScore aggregate & calculation
- 🔄 Security posture dashboard

### Phase 5: Advanced Features (Planned)
- 🔄 Workflow engine
- 🔄 Advanced analytics & ML-based insights
- 🔄 Integration APIs (SCIM, LDAP sync)
- 🔄 Performance optimization & scaling

---

## 6. Lợi Ích Của IAM Service

### 6.1 Cho Doanh Nghiệp
- ✅ Tuân thủ (GDPR, SOC2, ISO 27001)
- ✅ Quản lý rủi ro bảo mật tốt hơn
- ✅ Tự động hóa quy trình quản lý truy cập
- ✅ Báo cáo và audit trail đầy đủ
- ✅ Hỗ trợ multi-tenant/organization

### 6.2 Cho Developers
- ✅ API thống nhất cho identity & access
- ✅ Workflow engine linh hoạt
- ✅ Extensible architecture
- ✅ Comprehensive documentation
- ✅ SDK support

### 6.3 Cho End Users
- ✅ Self-service profile management
- ✅ Transparent access requests
- ✅ Better user experience
- ✅ Enhanced security với MFA & verification


---

## Kết Luận

Đề xuất này mở rộng thành `IAM Service` với đầy đủ các tính năng:
- **Identity Management** đầy đủ
- **Access Management** nâng cao
- **Governance & Compliance** toàn diện
- **Workflow automation** linh hoạt

Điều này biến service từ authentication/authorization cơ bản thành một IAM platform toàn diện, phù hợp cho enterprise.

---

## Quick Tips

### Mermaid Common Issues

- **Syntax Error**: Kiểm tra kỹ các dấu ngoặc `[]`, `{}`, `()` trong node label.
- **Connection**: Đảm bảo các mũi tên `-->`, `-.->` đúng cú pháp.
- **Indentation**: Subgraph cần thụt đầu dòng đúng cách.

### Color Pattern Reference

| Element | Fill Color | Stroke | Text | Usage |
|---------|------------|--------|------|-------|
| **Base** | `#202020` | `#505050` | `#fff` | Node thông thường |
| **Core** | `#1a237e` | `#3949ab` | `#fff` | Node trung tâm, quan trọng |
| **Module**| `#1b5e20` | `#43a047` | `#fff` | Module, service con |
| **DB** | `#4a148c` | `#7b1fa2` | `#fff` | Database, storage |
| **Warn** | `#b71c1c` | `#f44336` | `#fff` | Cảnh báo, lỗi |

### Visual Indicators

| Icon | Meaning |
|------|---------|
| ✅ | Đã hoàn thành / Tốt |
| 🔄 | Đang xử lý / Thay đổi |
| ⚠️ | Cảnh báo / Lưu ý |
| ❌ | Lỗi / Không khuyến khích |