pos-system/services/iam-service/README.md

# IAM Service - Enterprise Identity and Access Management

Enterprise-grade IAM (Identity and Access Management) service with comprehensive identity management, advanced access control, governance & compliance, RBAC/ABAC, Social Login, OIDC, JWT/Cookie management, and MFA support.

## Features

- ✅ **Advanced RBAC**: Role-based access control with permissions, roles, and policies
- ✅ **Social Login**: Google, Facebook, GitHub with circuit breaker
- ✅ **OIDC**: OpenID Connect provider and client support
- ✅ **JWT & Cookies**: Secure token management with access/refresh/ID tokens
- ✅ **MFA**: Multi-factor authentication with TOTP
- ✅ **Zero-Trust Security**: Device fingerprinting, geo-location, behavior analysis
- ✅ **Multi-layer Caching**: In-memory → Redis → CDN
- ✅ **Event Sourcing**: Complete audit logging
- ✅ **Dynamic Rate Limiting**: Based on user roles

## Architecture

For detailed architecture documentation, see [Architecture Documentation](docs/ARCHITECTURE.en.md) (English) or [Tài Liệu Kiến Trúc](docs/ARCHITECTURE.vi.md) (Tiếng Việt).

Quick overview:
```
services/iam-service/
├── src/
│   ├── config/          # Configuration files
│   ├── core/            # Core utilities (cache, security, events)
│   ├── modules/         # Feature modules
│   │   ├── auth/        # Core authentication
│   │   ├── rbac/        # RBAC system
│   │   ├── social/      # Social authentication
│   │   ├── oidc/        # OIDC implementation
│   │   ├── token/       # JWT & Cookie management
│   │   ├── session/     # Session management
│   │   ├── mfa/         # Multi-factor auth
│   │   ├── identity/    # Identity Management
│   │   ├── access/      # Access Management
│   │   └── governance/  # Governance & Compliance
│   ├── middlewares/     # Express middlewares
│   ├── repositories/    # Data access layer
│   └── routes/          # Route definitions
└── prisma/              # Database schema
```

## Setup

1. **Install dependencies:**
```bash
pnpm install
```

2. **Configure environment:**
```bash
cp env.local.example .env.local
# Edit .env.local with your configuration
```

3. **Setup database:**
```bash
pnpm prisma:generate
pnpm prisma:migrate
pnpm prisma:seed
```

4. **Run development server:**
```bash
pnpm dev
```

For detailed setup instructions, see [Quick Start Guide](docs/QUICK_START.md).

## API Endpoints

For complete API reference, see [API Reference Documentation](docs/API_REFERENCE.md).

### Authentication
- `POST /api/v1/auth/register` - Register new user
- `POST /api/v1/auth/login` - Login user
- `POST /api/v1/auth/logout` - Logout user
- `POST /api/v1/auth/refresh` - Refresh access token
- `GET /api/v1/auth/me` - Get current user

### Health
- `GET /health` - Health check
- `GET /health/ready` - Readiness probe
- `GET /health/live` - Liveness probe

## Documentation

- **[Quick Start Guide](docs/QUICK_START.md)** - Get up and running quickly
- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation
- **[Architecture](docs/ARCHITECTURE.en.md)** - Service architecture (English)
- **[Kiến Trúc](docs/ARCHITECTURE.vi.md)** - Service architecture (Tiếng Việt)
- **[Features](docs/FEATURES.md)** - Features overview and status
- **[Implementation](docs/IMPLEMENTATION.md)** - Implementation details

## Database Schema

The service uses Prisma with PostgreSQL. Key models:
- `User` - User accounts
- `Role` - RBAC roles
- `Permission` - Granular permissions
- `UserRole` - User-role assignments
- `UserPermission` - Direct user permissions
- `Session` - Active sessions
- `RefreshToken` - Refresh tokens
- `SocialAccount` - Social login accounts
- `MFADevice` - MFA devices
- `AuthEvent` - Audit events
- `Policy` - ABAC policies

## Security Features

- **Zero-Trust Architecture**: Every request is validated
- **Device Fingerprinting**: Track and validate devices
- **CSRF Protection**: Token-based CSRF protection
- **Rate Limiting**: Dynamic limits based on user roles
- **Audit Logging**: Complete event sourcing for compliance

## Performance

- **Multi-layer Cache**: L1 (memory) → L2 (Redis) → L3 (CDN)
- **Connection Pooling**: Optimized database connections
- **Token Caching**: Fast token validation
- **Permission Caching**: Cached permission checks

## Development

```bash
# Development
pnpm dev

# Build
pnpm build

# Test
pnpm test

# Lint
pnpm lint

# Type check
pnpm typecheck
```

## Production Deployment

See deployment guides in `/deployments/production/` for Kubernetes configuration.

## Migration from Auth Service

This service was migrated from `auth-service` to `iam-service` to reflect its expanded scope as a comprehensive Identity and Access Management platform.

### Backward Compatibility

All existing `/api/v1/auth/*`, `/api/v1/rbac/*`, `/api/v1/mfa/*`, and `/api/v1/sessions/*` endpoints remain unchanged and fully functional. No breaking changes were introduced.

### New Features

The IAM service extends the original auth-service with:
- **Identity Management**: User lifecycle, profiles, verification, organizations & groups
- **Access Management**: Access requests, reviews, analytics
- **Governance**: Compliance reporting, policy governance, risk management

See [Migration Guide](../../docs/en/guides/iam-migration.md) for detailed migration instructions.

## License

Proprietary - GoodGo Platform