pos-system/services/iam-service

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 (English) or Tài Liệu Kiến Trúc (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:

pnpm install

2. Configure environment:

cp env.local.example .env.local
# Edit .env.local with your configuration

3. Setup database:

pnpm prisma:generate
pnpm prisma:migrate
pnpm prisma:seed

4. Run development server:

pnpm dev

For detailed setup instructions, see Quick Start Guide.

API Endpoints

For complete API reference, see API Reference Documentation.

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 - Get up and running quickly
• API Reference - Complete API documentation
• Architecture - Service architecture (English)
• Kiến Trúc - Service architecture (Tiếng Việt)
• Features - Features overview and status
• Implementation - 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

# 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 for detailed migration instructions.

License

Proprietary - GoodGo Platform