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

Hướng Dẫn Migration: 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

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

Step 1: Backup (Quan Trọng!)

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

# Backup code (nếu cần rollback)
cp -r services/auth-service services/auth-service.backup

Step 2: Update Codebase

1. Update package references:

   # Tìm và thay thế trong code
   find . -type f -name "*.ts" -o -name "*.js" -o -name "*.json" | xargs sed -i '' 's/@goodgo\/auth-service/@goodgo\/iam-service/g'
   

2. Update environment variables:

   • Update SERVICE_NAME=iam-service trong tất cả env files
   • Update Docker Compose và Kubernetes configs

3. Run Prisma migration:

   cd services/iam-service
   pnpm prisma generate
   pnpm prisma migrate dev --name add_iam_models
   

Step 3: Deployment

Option A: Blue-Green Deployment (Khuyến Nghị)

1. Deploy iam-service mới:

   kubectl apply -f deployments/staging/kubernetes/iam-service.yaml
   

2. Verify iam-service hoạt động tốt

3. Switch traffic:

   • Update Ingress để point đến iam-service
   • Hoặc dùng weighted routing để gradually migrate

4. Monitor và verify

5. Decommission auth-service cũ sau khi verify

Option B: In-Place Migration

1. Deploy cả auth-service và iam-service cùng lúc

2. Gradually route traffic từ auth-service sang iam-service

3. Monitor performance và errors

4. Sau khi verify mọi thứ hoạt động tốt, có thể deprecate auth-service

Step 4: Rollback (Nếu Cần)

# Restore database
psql $DATABASE_URL < auth-service-backup.sql

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

Verification Checklist

• All existing endpoints still work
• Database migration successful
• New IAM endpoints working
• No breaking changes in responses
• Performance metrics acceptable
• Error rates normal
• All clients can connect successfully

Troubleshooting

Database Migration Issues

# Check migration status
pnpm prisma migrate status

# Reset migration (DEV ONLY!)
pnpm prisma migrate reset

Service Connection Issues

# Check service health
curl http://localhost:5001/health

# Check logs
docker logs iam-service-local
# hoặc
kubectl logs deployment/iam-service

Support

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

1. Check logs và error messages
2. Review migration guide này
3. Contact team lead hoặc DevOps team

---

Last Updated: 2024-12-30