Imagy Identity — Overview
Proposito
Imagy Identity es el dominio de autenticacion, autorizacion y gestion de tenants de la plataforma Imagy. Es el unico dominio actualmente en produccion y sirve como punto de entrada para todos los demas servicios. Consta de dos servicios complementarios: Identity Gateway (BFF, OIDC, reverse proxy) e Identity Management (CRUD de tenants, usuarios, roles, organizaciones).
Estado
✅ Funcional — En produccion.
Servicios
| Servicio | Repositorio | Puerto | Base de Datos | Descripcion |
|---|---|---|---|---|
| Identity Gateway | imagy-identity-gateway | 5001 | — (stateless, sesiones en Redis) | API Gateway, BFF, OIDC + PKCE, YARP reverse proxy |
| Identity Management | imagy-identity-management | 4000 | imagy_identity | Tenant Management, Control Plane, Keycloak Admin API |
Arquitectura
Responsabilidades
Identity Gateway (imagy-identity-gateway)
| Responsabilidad | Descripcion |
|---|---|
| Autenticacion OIDC + PKCE | Patron BFF — el frontend nunca maneja tokens directamente |
| Sesiones | Cookies httpOnly en Redis/Valkey con TTL configurable |
| Reverse Proxy | YARP enruta requests a servicios internos con JWT propagado |
| JWT Propagation | Propaga el JWT completo a downstream (no headers custom) |
| Tenant Routing | Resuelve tenant por subdominio, header X-Tenant-Slug, o query param |
| Rate Limiting | Limites por IP, por tenant y por endpoint |
| Security Headers | HSTS, CSP, X-Frame-Options, X-Content-Type-Options |
| CORS | Configuracion por tenant (origenes permitidos) |
| Back-channel Logout | Invalida sesiones cuando Keycloak notifica logout |
| Health Checks | Endpoints de salud para ALB y monitoring |
Identity Management (imagy-identity-management)
| Responsabilidad | Descripcion |
|---|---|
| CRUD Tenants | Onboarding, suspension, configuracion, eliminacion logica |
| CRUD Usuarios | Crear, listar, actualizar, desactivar usuarios dentro de un tenant |
| CRUD Roles | Definir roles con permisos granulares por modulo |
| Organizaciones | Gestion via Keycloak Organizations API (sub-agrupaciones dentro del tenant) |
| Delegated Admin | Administradores que gestionan multiples tenants |
| Temas Visuales | Branding por tenant (logo, colores, favicon, CSS custom) |
| Clientes OIDC/SAML | Configuracion de clientes de autenticacion por tenant |
| Modulos | Activar/desactivar modulos (ImagFlow, ImagLend, ImagSign) por tenant |
| Publicacion de Eventos | Publica eventos de ciclo de vida (user.created, tenant.created, etc.) |
Modelo de Multi-Tenancy
Identity implementa el patron realm-per-tenant en Keycloak:
Principios:
- Cada tenant tiene su propio realm en Keycloak (aislamiento total de credenciales)
- Los platform admins viven en el Master realm
- Identity Management usa la Keycloak Admin API para gestionar realms programaticamente
- Los usuarios de un tenant no pueden ver ni acceder a otros tenants
- Las organizaciones (Keycloak Organizations API) permiten sub-agrupaciones dentro de un tenant
Flujo de Autenticacion
Actores
| Actor | Descripcion | Realm |
|---|---|---|
| Platform Admin | Administra la plataforma completa, crea tenants, configura globalmente | Master |
| Delegated Admin | Administra uno o mas tenants asignados | Master (con scope limitado) |
| Tenant Admin | Administra su propio tenant (usuarios, roles, config) | Tenant realm |
| Operator | Opera dentro de un tenant (consulta, ejecuta acciones) | Tenant realm |
| End User | Usuario final que interactua con apps publicas | Tenant realm |
Integracion con Otros Dominios
Identity es consumido por todos los demas dominios de la plataforma:
| Dominio | Como usa Identity |
|---|---|
| ImagFlow | JWT para autenticacion, IIdentityContext para RLS, tenant routing |
| ImagLend | JWT, IIdentityContext, registro de usuario en pipeline (user_registration step) |
| ImagSign | JWT, IIdentityContext, verificacion de identidad del firmante |
| ImagID | Consume evento identity.user.created para crear perfil de sujeto |
| imagy-notifications | JWT para APIs admin, tenant context para templates |
| imagy-audit | Consume eventos de login/logout, registra acciones de Identity |
Registro de Usuario en Pipeline (ImagLend)
Cuando un usuario solicita un credito por primera vez, el pipeline de originacion puede crear automaticamente un usuario en el realm del tenant:
Ver ADR-010: User Registration in Pipeline.
Repositorios
- Gateway:
imagy-identity-gateway— .NET 8, YARP, Keycloak OIDC, Redis - Management:
imagy-identity-management— .NET 8, EF Core, Keycloak Admin API, MediatR - Base de datos:
imagy_identity - Equipo: Team Identity / Team Platform
Documentos Relacionados
- Modelo de Datos — Tablas de tenants, usuarios, roles, organizaciones
- API Reference — Endpoints del Gateway y Management
- Eventos — Eventos producidos por Identity
- ADR-001: JWT Propagation
- ADR-010: User Registration in Pipeline
- Steering: Identity Context