ImagLend — Integracion con Keycloak para Registro de Usuario

Proposito

Cuando un solicitante inicia el pipeline de originacion, el paso user_registration crea automaticamente un usuario en el realm de Keycloak del tenant. Esto permite que el solicitante tenga credenciales propias para re-ingresar al portal, ver el estado de su solicitud y acceder a sus creditos despues del desembolso.

Contexto

Ver ADR-010: User Registration in Pipeline para la decision arquitectonica.

Flujo de Registro

Datos Requeridos

Campo	Tipo	Obligatorio	Validacion
email	string	Si	Formato email, unico en el tenant
phone	string	Si	Formato telefono del pais, unico en el tenant
document_type	enum	Si	cc, ce, passport, nit
document_number	string	Si	Formato segun tipo
first_name	string	Si	Min 2 caracteres
last_name	string	Si	Min 2 caracteres

Validacion de Unicidad

Antes de crear el usuario, ImagLend verifica:

Campo	Contra que	Si ya existe
email	Tabla users del tenant	Ofrecer login en vez de registro
phone	Tabla users del tenant	Ofrecer login en vez de registro
document_number	Tabla users del tenant	Vincular solicitud al usuario existente

Request al Identity Management

POST /internal/users
X-Service-Auth: {service_token}
Content-Type: application/json

{
  "tenant_id": "tenant-uuid-001",
  "email": "maria.garcia@email.com",
  "first_name": "Maria",
  "last_name": "Garcia",
  "phone": "+593991234567",
  "document_type": "cc",
  "document_number": "1234567890",
  "role": "applicant",
  "send_credentials": true,
  "credential_strategy": "temporary_password",
  "origin": "credit_pipeline",
  "origin_reference": "application-uuid-001"
}

Response

{
  "data": {
    "user_id": "user-uuid-030",
    "keycloak_id": "kc-uuid-030",
    "temporary_password": "Tmp$2026xYz",
    "must_change_password": true,
    "status": "active"
  }
}

Estrategias de Credenciales

Estrategia	Descripcion	Cuando usar
temporary_password	Genera password temporal, usuario debe cambiar en primer login	Default — simple y seguro
magic_link	No genera password; login via link enviado por email	UX mas fluida, requiere email verificado
otp_only	Login solo con OTP por SMS	Usuarios sin email o con baja alfabetizacion digital

La estrategia se configura en el step user_registration del pipeline:

{
  "type": "user_registration",
  "config": {
    "credential_strategy": "temporary_password",
    "create_keycloak_user": true,
    "require_phone": true,
    "require_email": true
  }
}

Rol Applicant

El usuario creado recibe el rol applicant que otorga permisos limitados:

Permiso	Descripcion
application:read:own	Ver sus propias solicitudes
credit:read:own	Ver sus propios creditos
payment:read:own	Ver sus pagos
document:read:own	Descargar sus documentos firmados
device:read:own	Ver sus dispositivos
notification:read:own	Ver sus notificaciones

No puede: crear solicitudes desde el admin, ver datos de otros usuarios, gestionar productos.

Sesion Post-Registro

Despues del registro exitoso:

1. ImagLend recibe el user_id y keycloak_id
2. Crea una sesion autenticada para el wizard (el usuario ya no necesita access_token)
3. El wizard continua con JWT del usuario (propagado a servicios downstream)
4. Si el usuario abandona y vuelve, puede loguearse con sus credenciales

Evento Publicado

Identity Management publica identity.user.created que es consumido por:

• ImagID: Crea o vincula perfil de sujeto (subject_profiles) usando document_type + document_number
• imagy-audit: Registra el evento de creacion de usuario

Casos Edge

Caso	Comportamiento
Email ya existe en otro tenant	Se permite (cada tenant es independiente)
Email ya existe en ESTE tenant	Ofrecer login, no crear duplicado
Keycloak no disponible	Retornar 502, el usuario puede reintentar
Documento ya existe pero email diferente	Vincular al usuario existente (mismo sujeto, datos actualizados)
Usuario creado pero notificacion falla	Usuario se crea igual; notificacion se reintenta async

Seguridad

• El endpoint /internal/users solo es accesible por servicios internos (no expuesto al Gateway publico)
• Las credenciales temporales se envian por canal seguro (email o SMS, nunca en response al frontend)
• El password temporal expira en 24 horas si no se usa
• Se registra en audit: quien creo el usuario, desde que servicio, con que referencia

Documentos Relacionados

• ADR-010: User Registration in Pipeline
• Identity API Reference — Endpoint interno /internal/users
• Originacion Pipeline — Paso user_registration
• Identity Events — Evento identity.user.created