pos-system/docs/en/guides/iam-migration.md

Migration Guide: Auth Service → IAM Service

Tài liệu này hướng dẫn cách migrate từ auth-service sang iam-service.

Tổng Quan

IAM Service là phiên bản mở rộng của Auth Service với các tính năng bổ sung về Identity Management, Access Management, và Governance & Compliance. Tất cả các API endpoints của Auth Service vẫn được giữ nguyên để đảm bảo backward compatibility.

Backward Compatibility

✅ Tất cả các endpoints hiện tại vẫn hoạt động bình thường:

• /api/v1/auth/* - Authentication endpoints
• /api/v1/rbac/* - RBAC endpoints
• /api/v1/mfa/* - MFA endpoints
• /api/v1/sessions/* - Session management endpoints
• /api/v1/oidc/* - OIDC endpoints

Không có breaking changes. Các clients hiện tại có thể tiếp tục sử dụng các endpoints này mà không cần thay đổi.

Các Thay Đổi

1. Service Name

• Cũ: auth-service
• Mới: iam-service

2. Package Name

• Cũ: @goodgo/auth-service
• Mới: @goodgo/iam-service

3. Database Schema

Database schema được mở rộng với các models mới nhưng không xóa hoặc thay đổi các models hiện có:

Models mới được thêm:

• Organization - Quản lý tổ chức
• Group - Quản lý nhóm
• GroupMember - Thành viên nhóm
• GroupPermission - Quyền nhóm
• UserProfile - Profile mở rộng
• IdentityVerification - Xác thực danh tính
• AccessRequest - Yêu cầu truy cập
• AccessReview - Đánh giá truy cập
• ComplianceReport - Báo cáo tuân thủ
• PolicyTemplate - Template policy
• RiskScore - Điểm rủi ro

User model được mở rộng:

• Thêm field organizationId (optional)
• Thêm các relations mới (optional)

4. API Endpoints Mới

Identity Management

• /api/v1/identity/users/* - User lifecycle management
• /api/v1/identity/users/:id/profile - Profile management
• /api/v1/identity/verification/* - Identity verification
• /api/v1/identity/organizations/* - Organization management
• /api/v1/identity/groups/* - Group management

Access Management

• /api/v1/access/requests/* - Access requests
• /api/v1/access/reviews/* - Access reviews
• /api/v1/access/analytics/* - Access analytics

Governance

• /api/v1/governance/compliance/* - Compliance reports
• /api/v1/governance/policies/* - Policy governance
• /api/v1/governance/risk/* - Risk management
• /api/v1/governance/reports/* - Reporting dashboard

5. Environment Variables

Một số biến môi trường mới có thể được thêm trong tương lai cho các tính năng IAM nâng cao (email service, SMS service, file storage), nhưng không ảnh hưởng đến các biến hiện tại.

6. Deployment Configuration

Docker Compose:

• Service name: auth-service → iam-service
• Container name: auth-service-local → iam-service-local
• Traefik labels: Thêm routes mới cho /api/v1/identity/*, /api/v1/access/*, /api/v1/governance/*

Kubernetes:

• Deployment name: auth-service → iam-service
• Service name: auth-service → iam-service
• ConfigMap: auth-service-config → iam-service-config
• Secrets: auth-service-secrets → iam-service-secrets

Migration Steps

Bước 1: Backup

# Backup database
pg_dump $DATABASE_URL > auth-service-backup.sql

# Backup code
cp -r services/auth-service services/auth-service.backup

Bước 2: Database Migration

cd services/iam-service

# Generate Prisma client với schema mới
pnpm prisma generate

# Tạo migration
pnpm prisma migrate dev --name add_iam_models

# Verify migration
pnpm prisma studio  # Check database structure

Bước 3: Update Dependencies

# Install dependencies (nếu có package mới)
pnpm install

# Verify types compile
pnpm typecheck

Bước 4: Update Deployment

Local Development:

cd deployments/local
# Update docker-compose.yml (đã được cập nhật)
docker-compose up -d iam-service

Staging/Production:

• Update Kubernetes manifests
• Update ingress routes
• Update ConfigMaps và Secrets

Bước 5: Verify Backward Compatibility

Test tất cả các endpoints cũ vẫn hoạt động:

# Test auth endpoints
curl http://localhost/api/v1/auth/me

# Test RBAC endpoints  
curl http://localhost/api/v1/rbac/permissions

# Test MFA endpoints
curl http://localhost/api/v1/mfa/devices

Bước 6: Gradual Rollout

1. Dual Deployment (Optional):

   • Deploy cả auth-service và iam-service cùng lúc
   • Route traffic dần dần sang iam-service
   • Monitor errors và performance

2. Update Clients:

   • Update clients để sử dụng các endpoints mới nếu cần
   • Clients không cần update nếu chỉ dùng endpoints cũ

3. Deprecate Old Service:

   • Sau khi verify mọi thứ hoạt động tốt, có thể deprecate auth-service
   • Đảm bảo tất cả clients đã migrate sang iam-service

Rollback Plan

Nếu cần rollback:

1. Database Rollback:

   # Revert Prisma migration
   cd services/iam-service
   pnpm prisma migrate resolve --rolled-back <migration_name>
   
   # Hoặc restore từ backup
   psql $DATABASE_URL < auth-service-backup.sql
   

2. Service Rollback:

   # Switch back to auth-service in docker-compose
   # Hoặc revert Kubernetes deployment
   kubectl rollout undo deployment/auth-service
   

Breaking Changes

Không có breaking changes trong migration này. Tất cả các API endpoints và database models hiện có đều được giữ nguyên.

Notes

• Migration này là additive - chỉ thêm các tính năng mới, không xóa hoặc thay đổi tính năng cũ
• Database migrations là non-destructive - không xóa hoặc modify dữ liệu hiện có
• Clients có thể tiếp tục sử dụng các endpoints cũ mà không cần thay đổi

Support

Nếu gặp vấn đề trong quá trình migration, vui lòng:

1. Check logs: docker-compose logs iam-service
2. Verify database connection
3. Check environment variables
4. Review error messages và stack traces