Microservices
OpenGate IAM is composed of 10 microservices + 1 shared library, each with a clear bounded context.
On this page
opengate-common
Shared library included by all services. Not a runnable service.
opengate-common/src/main/java/io/opengate/iam/common/
├── dto/
│ └── PageResponse.java ← Generic paginated response record
├── event/
│ └── DomainEvent.java ← Kafka event envelope
└── exception/
├── OpenGateException.java ← Base typed exception
├── ResourceNotFoundException.java
└── GlobalExceptionHandler.java ← @RestControllerAdvice
Service Reference
Spring Cloud Gateway routes all external requests. Handles CORS, request logging (method, path, status, duration), and rate limiting. Routes to all downstream services by path prefix.
OAuth2 Authorization Server (Spring Auth Server 1.3). Issues RS256 JWTs, handles OIDC discovery, manages registered clients with PKCE. Publishes auth.login.success/failure to Kafka.
Full user lifecycle: create, update, delete, paginated list, password reset, email verification. Passwords hashed BCrypt(12). UserCredential stored separately from User entity.
Realm CRUD. Realms hold: name (slug, immutable), displayName, loginTheme, token lifespans, MFA requirement, SMTP settings (JSONB), password policy (JSONB). Seeds master realm on startup.
Role management, user-role mapping, policy evaluation. Evaluate endpoint returns PERMIT if user has any matching role, DENY otherwise. Supports composite roles and groups.
OAuth2 client registry. Client IDs generated as client-{uuid8}. Client secrets BCrypt-hashed. Supports public/confidential clients, PKCE, multiple redirect URIs and grant types.
TOTP via custom HMAC-SHA1 RFC 6238 (±1 window tolerance, QR URI, backup codes: 10 × 8-char). OTP: Redis-backed email/SMS codes with 10-minute TTL.
Redis-backed sessions with 8-hour TTL. Tracks per-user session set. Fields: sessionId, userId, realmId, clientIds, ipAddress, userAgent, timestamps. Publishes session.terminated on revocation.
Kafka consumer for user.created and auth.login.failure. Renders Thymeleaf HTML email templates (welcome, verify-email, reset-password, mfa-otp, login-alert) and sends via SMTP. Tracks SENT/FAILED in PostgreSQL.
Aggregated admin REST API. Proxies to realm, user, rbac, client, session services via reactive WebClient. Provides /admin/stats with aggregated counts from all services.
Inter-service Communication
┌─────────────────────────────────────────────────────────┐
│ Communication Patterns │
├─────────────────────────────────────────────────────────┤
│ │
│ Synchronous (HTTP via admin-api WebClient) │
│ ┌───────────┐ REST ┌────────┐ │
│ │ admin-api │ ──────► │ user │ │
│ │ :8089 │ │ rbac │ │
│ └───────────┘ │ realm │ │
│ └────────┘ │
│ │
│ Asynchronous (Kafka topics) │
│ ┌───────────┐ Kafka ┌──────────────────────┐ │
│ │ auth │ ──────► │ session-service │ │
│ │ user │ │ notification-service │ │
│ │ session │ └──────────────────────┘ │
│ └───────────┘ │
│ │
│ Redis (shared state) │
│ auth-service ──── token codes ────► Redis │
│ mfa-service ──── OTP codes ────► Redis │
│ session-svc ──── sessions ────► Redis │
│ gateway ──── rate limits ────► Redis │
└─────────────────────────────────────────────────────────┘
No direct service-to-service calls
Microservices do NOT call each other directly (except admin-api acting as an aggregator). All cross-service coordination happens through Kafka events or Redis shared state.