admin/pos-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d8faffd41dcb58efde1a5b493bb7736414f11fd2
pos-system/analysis/iam-architecture.md

17 KiB
Raw Blame History

IAM Service Architecture Analysis

Overview / Tổng quan

Service: iam-service - Enterprise-Grade Identity & Access Management TypeScript Files: 176 files Status: Production Ready (95% implementation) Last Updated: Jan 4, 2026

Module Structure / Cấu trúc Module

Production Modules (14 modules)

src/modules/
├── common/          # Shared utilities, base classes
├── feature/         # Feature flags (inherited from template)
├── health/          # Health check endpoints
├── metrics/         # Prometheus metrics
├── auth/            # Core authentication (login, register, logout)
├── rbac/            # Role-Based Access Control
├── token/           # JWT & Refresh token management
├── session/         # Session management with device tracking
├── mfa/             # Multi-Factor Authentication (TOTP)
├── social/          # Social OAuth (Google, Facebook, GitHub)
├── oidc/            # OpenID Connect (Provider + Client)
├── identity/        # Identity management (users, profiles, orgs)
├── access/          # Access management (requests, reviews, analytics)
└── governance/      # Governance & compliance (reports, policies, risk)

Module Breakdown

Core Authentication Modules

1. Auth Module

Purpose: Core authentication flows Key Features:

  • Email/password registration & login
  • Password reset & change
  • Bcrypt hashing (cost factor 12)
  • JWT token generation
  • CSRF protection

Endpoints:

POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
POST /api/v1/auth/change-password
GET  /api/v1/auth/me
2. Token Module

Purpose: JWT and refresh token management Features:

  • Access tokens (15min lifetime)
  • Refresh tokens (7 days lifetime)
  • Token rotation with family tracking
  • Secure HTTP-only cookies
  • Token blacklisting (on logout)
3. Session Module

Purpose: User session management Features:

  • Device fingerprinting
  • IP address tracking
  • Location analysis
  • Multiple concurrent sessions
  • Session listing & termination

Endpoints:

GET    /api/v1/sessions           # List user sessions
DELETE /api/v1/sessions/:id       # Terminate specific session
DELETE /api/v1/sessions/all       # Terminate all sessions
4. MFA Module

Purpose: Multi-Factor Authentication Features:

  • TOTP (Time-based One-Time Password)
  • QR code generation
  • Backup codes
  • Device management
  • Recovery procedures

Endpoints:

POST /api/v1/mfa/totp/enable
POST /api/v1/mfa/totp/verify
POST /api/v1/mfa/totp/validate
POST /api/v1/mfa/totp/disable
GET  /api/v1/mfa/devices
5. Social Module

Purpose: Social OAuth integration Supported Providers:

  • Google OAuth 2.0
  • Facebook Login
  • GitHub OAuth

Flow:

User → Redirect to Provider → Callback → Create/Link Account → JWT Token

Endpoints:

GET /api/v1/auth/social/google
GET /api/v1/auth/social/facebook
GET /api/v1/auth/social/github
GET /api/v1/auth/social/google/callback
GET /api/v1/auth/social/facebook/callback
GET /api/v1/auth/social/github/callback
6. OIDC Module

Purpose: OpenID Connect Provider & Client Features:

  • OIDC Provider implementation
  • OIDC Client for SSO
  • Discovery endpoint
  • UserInfo endpoint
  • Token introspection

Authorization Modules

7. RBAC Module

Purpose: Role-Based Access Control Permission Model: resource:action:scope Features:

  • Role management (CRUD)
  • Permission management
  • User-role assignments (with expiration)
  • User-permission overrides (direct permissions)
  • Permission caching (5min TTL)
  • Group-based permissions

Key Entities:

  • Role: Named collection of permissions (e.g., ADMIN, MANAGER, USER)
  • Permission: Granular access (e.g., users:create:org, posts:delete:own)
  • UserRole: User-role assignment (can expire)
  • UserPermission: Direct permission grants (override roles)

Endpoints:

GET    /api/v1/rbac/roles
POST   /api/v1/rbac/roles
GET    /api/v1/rbac/permissions
POST   /api/v1/users/:id/roles
DELETE /api/v1/users/:id/roles/:roleId
POST   /api/v1/users/:id/permissions

Permission Check Flow:

Request → Check Direct Permissions → Check Role Permissions → Check Group Permissions → Allow/Deny

Identity Management Modules

8. Identity Module

Purpose: User lifecycle & profile management Features:

  • User CRUD operations
  • Extended user profiles
  • Email/phone/document verification
  • Multi-tenant organizations
  • Groups with hierarchical structure
  • Bulk user import/export
  • User deactivation/reactivation

Database Models:

  • User - Core user accounts
  • UserProfile - Extended user information
  • Organization - Multi-tenant organizations
  • Group - User groups within orgs
  • GroupMember - Group membership
  • IdentityVerification - Verification records

Endpoints:

GET    /api/v1/identity/users
POST   /api/v1/identity/users
GET    /api/v1/identity/users/:id
PUT    /api/v1/identity/users/:id
POST   /api/v1/identity/users/:id/deactivate
POST   /api/v1/identity/users/:id/reactivate
GET    /api/v1/identity/users/:id/profile
PUT    /api/v1/identity/users/:id/profile
POST   /api/v1/identity/users/:id/avatar

Access Management Modules

9. Access Module

Purpose: Access request workflows & reviews Features:

  • Access request workflows with multi-person approval
  • Access reviews & certification campaigns
  • Access analytics & usage reporting
  • Anomaly detection
  • Just-In-Time (JIT) access
  • Temporary access grants

Database Models:

  • AccessRequest - Access request workflows
  • AccessRequestApprover - Multi-person approval chains
  • AccessReview - Access certification campaigns
  • AccessReviewItem - Individual review items

Endpoints:

POST /api/v1/access/requests
GET  /api/v1/access/requests
POST /api/v1/access/requests/:id/approve
POST /api/v1/access/requests/:id/reject
POST /api/v1/access/reviews
GET  /api/v1/access/reviews
POST /api/v1/access/reviews/:id/items/:itemId/review
GET  /api/v1/access/analytics/usage
10. Governance Module

Purpose: Compliance & governance reporting Features:

  • GDPR compliance reporting
  • SOC2 compliance reporting
  • ISO27001 compliance reporting
  • HIPAA compliance support
  • Policy templates & versioning
  • Risk scoring & management
  • Audit log analysis

Database Models:

  • ComplianceReport - Compliance reports (GDPR, SOC2, ISO27001, HIPAA)
  • PolicyTemplate - Reusable policy templates
  • RiskScore - User risk scoring

Endpoints:

POST /api/v1/governance/compliance/reports
GET  /api/v1/governance/compliance/reports
POST /api/v1/governance/compliance/reports/:id/generate
GET  /api/v1/governance/risk/scores
POST /api/v1/governance/risk/calculate
GET  /api/v1/governance/policies/templates

Core Services / Core Services

1. Multi-Layer Cache Service

Location: src/core/cache/ Pattern: L1 (Memory) → L2 (Redis) → L3 (Database)

Implementation:

  • L1 Cache: NodeCache (in-memory), 60s TTL, 10k keys max
  • L2 Cache: Redis, 5-15min TTL, distributed
  • L3: Prisma with connection pooling

Cached Data:

Data Type L1 TTL L2 TTL Use Case
User Data 60s 15min Profile, permissions
Permissions 60s 5min Authorization checks
User Roles 60s 5min Role assignments
Token Validation N/A Token lifetime JWT blacklist

Cache Invalidation:

// Pattern-based invalidation
await cacheService.invalidatePattern('user:123:*');

// Event-driven invalidation
onUserUpdate → invalidateCache('user:${userId}')
onPermissionChange → invalidateCache('user:${userId}:permissions')

2. Audit Service (Event Sourcing)

Location: src/core/events/ Purpose: Complete audit trail for compliance

Features:

  • Event sourcing for all authentication and authorization events
  • 7-year retention for compliance (GDPR, SOC2)
  • Correlation ID tracking
  • Event replay capability

Event Types:

enum AuditEventType {
  LOGIN_SUCCESS = 'LOGIN_SUCCESS',
  LOGIN_FAILURE = 'LOGIN_FAILURE',
  LOGOUT = 'LOGOUT',
  TOKEN_REFRESH = 'TOKEN_REFRESH',
  PASSWORD_CHANGE = 'PASSWORD_CHANGE',
  ROLE_ASSIGNED = 'ROLE_ASSIGNED',
  PERMISSION_GRANTED = 'PERMISSION_GRANTED',
  ACCESS_DENIED = 'ACCESS_DENIED',
  SESSION_CREATED = 'SESSION_CREATED',
  SESSION_TERMINATED = 'SESSION_TERMINATED',
  MFA_ENABLED = 'MFA_ENABLED',
  // ... many more
}

Database Model:

model AuthEvent {
  id            String   @id @default(cuid())
  eventType     String   // AuditEventType
  userId        String?
  email         String?
  ipAddress     String?
  userAgent     String?
  success       Boolean
  metadata      Json?
  correlationId String?
  createdAt     DateTime @default(now())
  
  @@index([userId, createdAt])
  @@index([eventType, createdAt])
  @@index([correlationId])
}

3. Security Service (Zero-Trust Validator)

Location: src/core/security/ Purpose: Zero-trust security validation

Features:

  • Device fingerprinting
  • IP address analysis
  • Location validation
  • Behavioral analysis
  • Risk-based authentication
  • Anomaly detection

Zero-Trust Checks:

1. Valid JWT token? ✓
2. Token not blacklisted? ✓
3. Session still active? ✓
4. Device fingerprint matches? ✓
5. IP address in allowed range? ✓
6. No suspicious behavior detected? ✓
→ ALLOW REQUEST

4. Encryption Service

Location: src/core/security/encryption.service.ts Algorithm: AES-256-GCM Purpose: Encrypt PII at rest

Features:

  • Symmetric encryption for sensitive data
  • IV (Initialization Vector) per encryption
  • Authentication tag for integrity
  • Key rotation support

Usage:

// Encrypt sensitive data
const encrypted = encryptionService.encrypt(ssn);
// Store: "iv:tag:ciphertext"

// Decrypt when needed
const ssn = encryptionService.decrypt(encrypted);

Middleware Stack / Stack Middleware

// Execution Order (from main.ts)
1. Helmet                      // Security headers
2. CORS                        // Cross-origin config
3. Rate Limiting               // Dynamic rate limiting (by role)
4. Correlation ID              // Request tracing
5. Request Logger              // Structured logging
6. Zero-Trust Validator        // Security validation
7. Body Parsers                // JSON, URL-encoded
8. Cookie Parser               // Parse cookies
9. Metrics                     // Prometheus instrumentation
10. Routes                     // API routes
11. Not Found Handler          // 404 handling
12. Error Handler              // Global error handling (LAST)

Dynamic Rate Limiting

Implementation: Redis-backed distributed rate limiting

Limits by Role:

const rateLimitsByRole = {
  anonymous: { windowMs: 15 * 60 * 1000, max: 50 },      // 50 req/15min
  user: { windowMs: 15 * 60 * 1000, max: 100 },          // 100 req/15min
  moderator: { windowMs: 15 * 60 * 1000, max: 300 },     // 300 req/15min
  admin: { windowMs: 15 * 60 * 1000, max: 500 },         // 500 req/15min
  superadmin: { windowMs: 15 * 60 * 1000, max: 1000 },   // 1000 req/15min
};

Login-Specific Limit:

const loginLimiter = {
  windowMs: 15 * 60 * 1000,
  max: 5,  // 5 login attempts per 15 minutes
  message: 'Too many login attempts, please try again later',
};

Database Schema / Schema Database

Database: PostgreSQL 14+ ORM: Prisma Total Models: 30+

Core Models

Authentication

  • User - User accounts (email, password, MFA status)
  • Session - Active sessions (device, IP, location)
  • RefreshToken - Refresh tokens (with family tracking)
  • AuthEvent - Audit log (event sourcing)
  • SocialAccount - Linked OAuth accounts
  • MFADevice - TOTP and WebAuthn devices

Authorization

  • Role - Named roles (ADMIN, MANAGER, USER)
  • Permission - Granular permissions (resource:action:scope)
  • UserRole - User-role assignments (with expiration)
  • RolePermission - Role-permission mappings
  • UserPermission - Direct user permissions (override roles)
  • Policy - ABAC policies (JSON Logic conditions)

Identity

  • Organization - Multi-tenant organizations
  • Group - User groups within organizations
  • GroupMember - Group membership (with roles)
  • UserProfile - Extended user information
  • IdentityVerification - Email/phone/document verification

Access Management

  • AccessRequest - Access request workflows
  • AccessRequestApprover - Multi-person approval chains
  • AccessReview - Access certification campaigns
  • AccessReviewItem - Individual review items

Governance

  • ComplianceReport - GDPR, SOC2, ISO27001, HIPAA reports
  • PolicyTemplate - Reusable policy templates
  • RiskScore - User risk scores

API Surface / Bề mặt API

Total Endpoints: 50+ Base Path: /api/v1

Endpoint Categories

Category Endpoints Module
Authentication 10+ auth, token, session
Social Auth 6 social
OIDC 5+ oidc
MFA 5 mfa
RBAC 8 rbac
Identity 12+ identity
Access 8+ access
Governance 6+ governance
Health 3 health
Metrics 1 metrics

Security Features / Tính năng Bảo mật

Defense-in-Depth Layers

  1. Network Layer:

    • HTTPS/TLS enforcement
    • CORS configuration
    • Rate limiting (distributed)

  2. Application Layer:

    • Helmet (security headers)
    • Input validation (Zod)
    • SQL injection prevention (Prisma ORM)
    • XSS prevention (CSP)

  3. Authentication Layer:

    • Bcrypt (cost factor 12)
    • JWT with short lifetime (15min)
    • Refresh token rotation
    • MFA (TOTP)
    • Social OAuth

  4. Authorization Layer:

    • RBAC (role-based)
    • ABAC (attribute-based)
    • Direct permissions (override roles)
    • Permission caching

  5. Data Layer:

    • AES-256-GCM encryption for PII
    • Token hashing (SHA-256)
    • Password hashing (bcrypt)

  6. Audit Layer:

    • Event sourcing
    • Correlation IDs
    • 7-year retention
    • Compliance reporting

Performance Optimizations / Tối ưu Hiệu suất

Caching Strategy

  • Cache Hit Rate: 80-90% for permissions
  • Response Time: P95 < 100ms
  • Token Validation: < 1ms (L1 cache hit)
  • Permission Check: < 5ms (L2 cache hit)

Database Optimizations

  • Connection pooling (Prisma default: 10)
  • Indexed queries (25+ indexes)
  • Selective field fetching
  • Batch operations where possible

Redis Optimizations

  • Connection pooling
  • Pipeline operations
  • Pub/Sub for cache invalidation
  • Distributed rate limiting

Observability / Khả năng quan sát

Metrics (Prometheus)

  • HTTP request duration (by endpoint, status)
  • HTTP request count
  • Active sessions (gauge)
  • Cache hit/miss ratio
  • Database query duration
  • Authentication success/failure rate
  • Authorization checks (allow/deny)

Logging (Winston)

  • Structured JSON logs
  • Correlation IDs in every log
  • Request/response logging
  • Error stack traces (dev only)
  • Audit event logging

Tracing (OpenTelemetry + Jaeger)

  • HTTP request spans
  • Database query spans
  • Cache operation spans
  • External API call spans
  • Authentication flow spans

Health Checks

  • /health/live - Liveness (is process running?)
  • /health/ready - Readiness (can serve traffic? checks DB + Redis)
  • /health - Full health (with dependency status)

Production Readiness / Sẵn sàng Production

  • ✅ Multi-layer caching (L1/L2/L3)
  • ✅ Zero-trust architecture
  • ✅ Device fingerprinting
  • ✅ Dynamic rate limiting
  • ✅ Event sourcing for audit
  • ✅ Compliance reporting (GDPR, SOC2, ISO27001, HIPAA)
  • ✅ Multi-factor authentication
  • ✅ Social OAuth integration
  • ✅ OpenID Connect
  • ✅ RBAC + ABAC authorization
  • ✅ Encryption for PII
  • ✅ Comprehensive logging
  • ✅ Prometheus metrics
  • ✅ Jaeger tracing
  • ✅ Health checks (K8s compatible)
  • ✅ Docker deployment
  • ✅ Kubernetes manifests
  • ✅ Graceful shutdown
  • ✅ Connection pooling

Comparison with Template / So sánh với Template

Feature Template IAM Service
Modules 4 14
TypeScript Files 38 176
Database Models 1 (example) 30+
API Endpoints 5 (example) 50+
Authentication ❌ ✅ (7 methods)
Authorization ❌ ✅ (RBAC + ABAC)
Caching ❌ ✅ (3-layer)
Rate Limiting ❌ ✅ (Dynamic by role)
Audit Logging Basic ✅ (Event sourcing)
Security Basic (Helmet) ✅ (Zero-trust)
MFA ❌ ✅ (TOTP)
Social OAuth ❌ ✅ (3 providers)
OIDC ❌ ✅ (Provider + Client)
Compliance ❌ ✅ (4 frameworks)
Encryption ❌ ✅ (AES-256-GCM)

Summary / Tóm tắt

iam-service is an enterprise-grade IAM platform built on top of the _template foundation, demonstrating:

  • Complete authentication system (password, social, OIDC, MFA)
  • Advanced authorization (RBAC + ABAC + direct permissions)
  • Zero-trust security (device fingerprinting, behavioral analysis)
  • High performance (multi-layer caching, 80-90% cache hit rate)
  • Compliance-ready (GDPR, SOC2, ISO27001, HIPAA reporting)
  • Production-hardened (95% implementation complete)

It showcases real-world patterns for:

  • Distributed caching
  • Event sourcing
  • Zero-trust architecture
  • Multi-tenant support
  • Access governance
  • Compliance automation
Reference in New Issue View Git Blame Copy Permalink