Chapter 6: Identity and Access Management
The IAM service is the security foundation of the MATIH Enterprise Platform. It governs authentication, authorization, multi-factor authentication, API key management, session tracking, OAuth2 flows, and user impersonation across the entire platform.
Learning Objectives
- Understand the IAM service architecture, domain model, and integration points
- Implement authentication flows including login, registration, MFA, and OAuth2
- Configure RBAC with roles, permissions, and OPA policy evaluation
- Manage API keys with scoped permissions, rotation, and IP whitelisting
- Administer sessions, devices, and user impersonation for support workflows
Details
- JWT token structure and validation
- OAuth2 grant types
- Spring Security filter chain
- Multi-factor authentication fundamentals
- Ch. 7: Tenant Lifecycle
- Ch. 8: Platform Services
The Identity and Access Management (IAM) service is the security foundation of the MATIH Enterprise Platform. Every API request across both the control plane and data plane passes through IAM-issued JWT tokens for authentication and authorization. The service manages the complete identity lifecycle from user registration through session termination.
What You Will Learn
By the end of this chapter, you will understand:
- The IAM architecture including the service boundary, domain model, integration points, and the relationship between the IAM service and the shared commons-java JWT library
- Authentication flows covering credential-based login, OAuth2 authorization code and client credentials grants, SSO via Keycloak, and the adaptive risk assessment engine
- Multi-factor authentication enrollment, verification, and recovery for TOTP, SMS, and email channels with backup code management and per-tenant MFA policies
- User management including CRUD operations, role assignment, account lockout, password policies, and self-service access requests
- RBAC model with hierarchical roles, fine-grained permissions using resource:action patterns, permission caching, and OPA integration
- API key management with scoped permissions, automatic and manual rotation, IP whitelisting, and rate limiting
- Session management covering active session tracking, device fingerprinting, trusted device management, and administrative session revocation
- OAuth2 implementation including client registration, authorization code flow with PKCE, token issuance, introspection, and revocation
- User impersonation for admin troubleshooting with full audit trail and compliance controls
- The complete API surface with endpoint specifications, request and response schemas, error codes, and rate limiting behavior
Chapter Structure
| Section | Description | Audience |
|---|---|---|
| IAM Architecture | Service internals, domain model, security layers, and integration topology | Architects, backend engineers |
| Authentication | Login, registration, email verification, password reset, tokens, and logout | Backend engineers, security engineers |
| Multi-Factor Authentication | TOTP, SMS, email MFA enrollment, verification, policies, and recovery | Backend engineers, security engineers |
| User Management | User CRUD, role assignment, enable/disable, lockout, password policies, access requests | Backend engineers, platform operators |
| Roles and Permissions | RBAC model, role management, permission model, custom roles, caching, OPA integration | Architects, security engineers |
| API Keys | Key creation, rotation, scopes, rate limits, IP whitelisting | Backend engineers, API consumers |
| Session Management | Session lifecycle, device management, trusted devices | Backend engineers, security engineers |
| OAuth2 | Client management, authorization code flow, token management | Backend engineers, integration engineers |
| Impersonation | Starting/ending sessions, audit trail, compliance | Platform operators, security engineers |
| API Reference | Complete endpoint catalog with request/response schemas | All developers |
Service at a Glance
| Property | Value |
|---|---|
| Service Name | iam-service |
| Technology | Spring Boot 3.2, Java 21 |
| Port | 8081 |
| Database | PostgreSQL (control plane database) |
| Cache | Redis (session and permission caching) |
| JWT Library | JJWT 0.12.3 with HS256 signing |
| MFA Providers | TOTP (RFC 6238), SMS (Twilio), Email |
| SSO Integration | Keycloak (OIDC/SAML), OAuth2 providers |
| Policy Engine | Open Policy Agent (OPA) |
| API Documentation | OpenAPI 3.0 via SpringDoc |
| Controllers | 16 REST controllers |
| Services | 23 business services |
| Repositories | 25 JPA repositories |
Component Overview
Key Design Principles
Tenant isolation from day one. Every JWT token carries a tenant_id claim. Every database query is scoped by tenant. There is no code path where a user in one tenant can access resources belonging to another.
Defense in depth. Authentication is not a single gate but a series of layered checks: credential validation, MFA challenge, device fingerprinting, geo-location anomaly detection, and rate limiting. Each layer operates independently and can block a request.
Zero-trust security posture. Sessions are continuously evaluated for risk. A session that was valid at login can be elevated to require re-authentication if the risk profile changes (new IP, new device, unusual access pattern).
Standards compliance. The OAuth2 implementation follows RFC 6749 and RFC 7636 (PKCE). JWT tokens follow RFC 7519. TOTP follows RFC 6238. The permission model follows the resource:action pattern for fine-grained access control.
How This Chapter Connects
The IAM service is consumed by every other service in the platform. The API Gateway validates JWT tokens on every inbound request and extracts tenant context. The Tenant Service calls back to IAM during provisioning to create the initial admin user and configure tenant-specific authentication policies. The data plane services rely on the commons-java JwtTokenProvider to validate tokens forwarded through the gateway.
Understanding the token claims structure documented in Authentication is a prerequisite for working with any authenticated API endpoint across the platform.
Prerequisites
To get the most from this chapter, you should be familiar with:
- JWT token structure and validation concepts
- OAuth2 grant types (authorization code, client credentials, refresh token)
- Multi-factor authentication fundamentals
- Spring Security filter chain architecture
- RESTful API design patterns
Begin with the IAM Architecture to understand the service internals before diving into individual authentication flows.