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

cd deployments/local
docker-compose up -d

Chạy Local

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

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:

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

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

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:

{
  "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ệ:

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)

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

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

Client Credentials (Service-to-Service)

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ử

dotnet test

Triển Khai

Docker Build

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
• ASP.NET Core Identity
• OAuth2 Specification