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

# IAM Service .NET 10

> **Service IAM (Identity and Access Management) .NET 10 với OAuth2/OIDC sử dụng OpenIddict.**

## Tổng Quan

IAM Service cung cấp các chức năng quản lý danh tính và truy cập:

- **OAuth2/OIDC** - Authentication với OpenIddict
- **User Management** - CRUD operations cho users
- **Password Management** - Đổi mật khẩu
- **Token Management** - Issue, refresh, revoke tokens
- **CQRS Pattern** - MediatR cho Commands/Queries
- **Clean Architecture** - Domain, Infrastructure, API layers

## Yêu Cầu

| Yêu cầu | Phiên bản |
|---------|-----------|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL | 15+ |

## Bắt Đầu Nhanh

### Chạy với Docker

```bash
cd deployments/local
docker-compose up -d
```

### Chạy Local

```bash
cd services/iam-service-net
dotnet restore
dotnet build
dotnet run --project src/IamService.API
```

## API Endpoints

### Authentication (`/api/v1/auth`)

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

### User Management (`/api/v1/users`)

| Method | Endpoint | Mô Tả | Auth |
|--------|----------|-------|------|
| `GET` | `/api/v1/users` | Lấy danh sách users (phân trang) | ✅ |
| `GET` | `/api/v1/users/me` | Lấy 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 thông tin user | ✅ |
| `DELETE` | `/api/v1/users/{id}` | Xóa user (soft delete) | ✅ |

### Health Checks

| Endpoint | Mục Đích |
|----------|----------|
| `/health` | Trạng thái health đầy đủ |
| `/health/live` | Kiểm tra sống |
| `/health/ready` | Kiểm tra sẵn sàng |

## Quy Trình Xác Thực

### Bước 1: Đăng Ký User Mới

```bash
curl -X POST http://localhost:5001/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "Password123!",
    "firstName": "John",
    "lastName": "Doe"
  }'
```

**Response:**
```json
{
  "success": true,
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com"
  }
}
```

### Bước 2: Đăng Nhập (Password Grant)

```bash
curl -X POST http://localhost:5001/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "username=user@example.com" \
  -d "password=Password123!" \
  -d "scope=openid profile email offline_access"
```

**Response:**
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
  "scope": "openid profile email offline_access"
}
```

### Bước 3: Sử Dụng Access Token

Sử dụng `access_token` trong header `Authorization` cho các API được bảo vệ:

```bash
curl http://localhost:5001/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9..."
```

### Bước 4: Làm Mới Token (Khi Access Token Hết Hạn)

```bash
curl -X POST http://localhost:5001/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9..."
```

### Bước 5: Đăng Xuất

```bash
curl -X POST http://localhost:5001/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Client Credentials (Service-to-Service)

```bash
curl -X POST http://localhost:5001/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=goodgo-service" \
  -d "client_secret=service-secret" \
  -d "scope=api"
```

## Swagger UI

Sau khi chạy service, truy cập Swagger UI tại:
- **Local**: http://localhost:5001/swagger
- **Docker**: http://localhost/api/v1/iam/swagger

## Cấu Hình

### Biến Môi Trường

| Biến | Mô Tả | Mặc định |
|------|-------|----------|
| `ASPNETCORE_ENVIRONMENT` | Môi trường | `Development` |
| `DATABASE_URL` | PostgreSQL connection | - |
| `JWT_SECRET` | Secret ký JWT (32+ ký tự) | - |

## Kiểm Thử

```bash
dotnet test
```

## Triển Khai

### Docker Build

```bash
docker build -t goodgo/iam-service:latest .
docker run -p 5001:8080 --env-file .env goodgo/iam-service:latest
```

## Tài Nguyên

- [OpenIddict Documentation](https://documentation.openiddict.com/)
- [ASP.NET Core Identity](https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity)
- [OAuth2 Specification](https://oauth.net/2/)