C4 — Componentes

El nivel C4 Component descompone cada contenedor de la plataforma en sus unidades internas con responsabilidades definidas. Este documento ofrece una visión cruzada de los tres contenedores principales: Keycloak, Traefik y el microservicio Spring WebFlux, mostrando sus componentes y las relaciones entre ellos.

Diagrama general de componentes

flowchart TB
    subgraph Traefik["Traefik (Reverse Proxy)"]
        EP["EntryPoints\n:80 / :443"]
        Router["Routers\n(reglas host/path)"]
        MW["Middlewares\n(headers, rate-limit, redirect)"]
        TLS["TLS Termination"]
        CM["Certificate Manager\n(ACME / Let's Encrypt)"]
        EP --> Router
        Router --> MW
        MW --> TLS
        TLS --> CM
    end

    subgraph Keycloak["Keycloak 26.x (Identity Provider)"]
        AE["Authentication Engine\n(flujos, MFA, PKCE)"]
        TS["Token Service\n(issuer, signer, revocación)"]
        AA["Admin REST API\n(/admin/realms/*)"]
        US["User Storage\n(PostgreSQL adapter)"]
        IB["Identity Broker\n(SAML, OIDC externo)"]
        CR["Client Registry"]
        AE --> TS
        AE --> US
        AE --> CR
        AA --> AE
        AA --> CR
        IB --> AE
    end

    subgraph WebFlux["Spring WebFlux (Resource Server)"]
        RF["RouterFunctions\n(rutas reactivas)"]
        SFC["SecurityFilterChain\n(ReactiveSecurityConfig)"]
        JV["JWT Validator\n(ReactiveJwtDecoder)"]
        AM["AuthorizationManager"]
        BH["Business Handlers"]
        RF --> SFC
        SFC --> JV
        JV --> AM
        AM --> BH
    end

    Internet((Internet)) -->|HTTPS 443| EP
    MW -->|proxy HTTP| Keycloak
    MW -->|proxy HTTP| WebFlux
    JV -->|JWKS fetch| TS
    BH -->|R2DBC| DB[(PostgreSQL)]

Tabla de componentes por contenedor

Keycloak

Componente	Responsabilidad	Protocolo expuesto
Authentication Engine	Ejecuta flujos OAuth 2.1/OIDC (Authorization Code, Client Credentials, Device Flow). Coordina MFA y PKCE.	OIDC / OAuth 2.1
Token Service	Genera, firma (RS256/ES256) y valida tokens. Gestiona revocación y sesiones activas.	JWT / JWKS
Admin REST API	Gestión programática de realms, clientes, usuarios y roles vía HTTP.	REST / JSON
User Storage	Adaptador JDBC contra PostgreSQL. Persiste usuarios, credenciales y atributos de perfil.	SQL (interna)
Identity Broker	Federar autenticación con IDPs externos (SAML 2.0, OIDC de terceros).	SAML 2.0 / OIDC
Client Registry	Almacena configuración de clientes OAuth2: scopes, redirect URIs, secretos, tipo de acceso.	Interna (BD)

Traefik

Componente	Responsabilidad	Clave de configuración
EntryPoints	Escucha en puertos 80 y 443. Punto de entrada único para todo el tráfico externo.	entryPoints.web, entryPoints.websecure
Routers	Aplica reglas de routing por Host y PathPrefix. Selecciona el servicio destino correcto.	rule: Host(...)
Middlewares	Añade security headers, redirect HTTP→HTTPS, rate limiting por IP/ruta.	headers, redirectScheme, rateLimit
TLS Termination	Descifra TLS en el edge. Las comunicaciones internas son HTTP plano en la red Docker privada.	tls: certResolver
Certificate Manager	Gestiona certificados ACME (Let's Encrypt). Renueva automáticamente antes de la expiración.	certificatesResolvers.letsencrypt

Spring WebFlux

Componente	Responsabilidad	Tipo
RouterFunctions	Define rutas HTTP de forma funcional sin anotaciones de controlador.	RouterFunction<ServerResponse>
Business Handlers	Implementa la lógica de aplicación. Recibe ServerRequest, retorna Mono<ServerResponse>.	HandlerFunction<ServerResponse>
SecurityFilterChain	Configura la cadena de filtros reactiva. Declara rutas públicas y rutas con scope requerido.	SecurityWebFilterChain
JWT Validator	Descarga y cachea JWKS desde Keycloak. Valida firma, expiración, issuer y audience.	ReactiveJwtDecoder
AuthorizationManager	Evalúa scopes y roles del JWT contra cada ruta protegida.	ReactiveAuthorizationManager

Flujo de petición autenticada entre componentes

sequenceDiagram
    actor Cliente
    participant EP as Traefik EntryPoint
    participant SFC as Spring SecurityFilterChain
    participant JV as JWT Validator
    participant TS as Keycloak Token Service
    participant BH as Business Handler

    Cliente->>EP: GET /api/recurso Bearer: <token>
    EP->>SFC: Forward (HTTP interno)
    SFC->>JV: Extraer y validar JWT
    JV->>TS: GET /.well-known/jwks.json (cacheado 5 min)
    TS-->>JV: Claves públicas RSA
    JV-->>SFC: Claims validados: sub, scope, exp
    SFC->>BH: Ejecutar con SecurityContext poblado
    BH-->>Cliente: 200 OK payload

Principios de diseño aplicados

• Sin estado en el gateway: Traefik no almacena sesiones; la identidad viaja completamente en el JWT firmado.
• Validación local del token: Spring WebFlux valida el JWT con clave pública JWKS; no llama a Keycloak por cada petición.
• Rotación automática de claves: Keycloak rota claves de firma periódicamente; ReactiveJwtDecoder refresca JWKS al detectar un kid desconocido.
• Defensa en capas: Traefik aplica rate limiting antes de que la petición llegue a la aplicación, reduciendo la superficie de ataque.