Usuario (User)

El sistema de usuarios en ValerIA proporciona un control de acceso granular y flexible para gestionar quién puede acceder a qué funcionalidades del sistema. Los usuarios son la base del sistema de autenticación y autorización.

¿Qué es un Usuario?

Un usuario en ValerIA es una entidad que representa a una persona o sistema automatizado que puede interactuar con la plataforma. Cada usuario tiene un conjunto de propiedades que definen su identidad, permisos y configuraciones específicas.

Estructura del Usuario

El usuario está constituido por la siguiente información en formato JSON:

Campos Básicos

Campo	Tipo	Descripción	Requerido	Ejemplo
name	String	Nombre real del usuario	✅	"Luis"
surname	String	Apellidos del usuario	❌	"Smith"
nickname	String	Nombre de usuario o alias	❌	"Luisito"
email	String	Correo electrónico (único)	✅	"luis@test.com"
password	String	Contraseña del usuario	✅	"secretPAsSwOrd"

Control de Acceso

Campo	Tipo	Descripción	Enlace	Ejemplo
role	String	Rol del usuario en el sistema	Ver Roles	"user", "admin", "robot"
groups	Array[String]	Grupos a los que pertenece	Ver Grupos	["administración", "legal"]
policies	Array[String]	Políticas de acceso específicas	Ver Políticas	["readuser", "writeuser"]

Estado y Control

Campo	Tipo	Descripción	Por Defecto	Uso
active	Boolean	Si el usuario está activo	true	Habilitar/deshabilitar acceso
devicecheck	Boolean	Control de dispositivos habilitado	false	Seguridad adicional
activity	Boolean	Seguimiento de tiempo de trabajo	false	Control laboral
presencecontrol	Boolean	Control de presencia	false	Gestión de asistencia

Campos del Sistema

Campo	Tipo	Descripción	Generado
timestamp	Date	Fecha de creación del usuario	Automático
hash	String	Hash de la contraseña	Automático
sign	String	Firma de seguridad del usuario	Automático
apikey	String	Clave API para usuarios robot	Automático

Ejemplo de Usuario Estándar

{
  "name": "Luis",
  "surname": "Smith", 
  "nickname": "Luisito",
  "email": "luis@test.com",
  "password": "secretPAsSwOrd",
  "role": "user",
  "groups": ["administración"],
  "policies": [
    "readuser",
    "writeuser",
    "readdossier",
    "writedossier"
  ],
  "active": true,
  "devicecheck": false,
  "activity": true,
  "presencecontrol": false
}

Control de Dispositivos

Cuando devicecheck está habilitado, el sistema rastrea información detallada de cada dispositivo:

Información de Dispositivos

Campo	Descripción	Ejemplo
first	Primera conexión	2023-01-15T10:30:00Z
last	Última conexión	2023-12-01T14:22:00Z
id	Identificador único del dispositivo	"device_abc123"
name	Nombre del dispositivo	"MacBook Pro de Luis"
ip	Dirección IP	"192.168.1.100"
OS	Sistema operativo	"macOS"
browser	Navegador utilizado	"Chrome"
location	Ubicación geográfica	"Madrid, España"
permited	Si está autorizado	true/false

Ejemplo de Estructura de Dispositivos

{
  "devices": [
    {
      "first": "2023-01-15T10:30:00Z",
      "last": "2023-12-01T14:22:00Z", 
      "id": "device_abc123",
      "name": "MacBook Pro de Luis",
      "ip": "192.168.1.100",
      "OS": "macOS",
      "OSversion": "13.1",
      "browser": "Chrome",
      "version": "108.0.0.0",
      "platform": "Intel",
      "activity": true,
      "TZ": "Europe/Madrid",
      "location": "Madrid, España",
      "visualcheck": false,
      "permited": true
    }
  ]
}

Usuarios Robot

Los usuarios robot son un tipo especial diseñado para integración de sistemas y automatización:

Características Especiales

• No pueden autenticarse en la aplicación web
• Solo acceso por API usando robotKey
• Permisos por defecto amplios (se recomienda limitarlos)
• Ideal para scripts y sistemas externos

Campo Adicional para Robots

Campo	Tipo	Descripción	Generación
robotKey	String	Clave de autenticación para API	Automática

Ejemplo de Usuario Robot

{
  "name": "Bot Integración",
  "email": "bot@miempresa.com",
  "password": "automaticPassword123",
  "role": "robot",
  "policies": [
    "readdossier",
    "writedossier", 
    "readmovement",
    "writemovement"
  ],
  "active": true,
  "robotKey": "rk_abc123def456ghi789"
}

Autenticación de Robots

Los usuarios robot se autentican usando su robotKey en lugar del sistema JWT estándar:

# Ejemplo de llamada API con robot
curl -X GET \
  https://api.valeria.com/v1/dossier/list \
  -H "Authorization: Robot rk_abc123def456ghi789"

Gestión de Usuarios

Creación de Usuarios

Los usuarios se pueden crear desde:

1. Interfaz Web: Sección /user de la aplicación
2. API REST: Endpoint /v1/user/create
3. Importación: Desde archivos CSV/JSON

Políticas Obligatorias

Todo usuario (excepto robots) debe tener como mínimo:

• readuser: Para leer información de usuarios
• writeuser: Para gestionar usuarios

Estados del Usuario

Estado	Descripción	Efecto
active: true	Usuario activo	Puede acceder al sistema
active: false	Usuario inactivo	Bloqueado, no puede acceder
devicecheck: true	Control habilitado	Rastrea y controla dispositivos
activity: true	Seguimiento activo	Registra tiempo de trabajo

Seguridad y Mejores Prácticas

Contraseñas

• Almacenadas como hash usando algoritmos seguros
• Nunca se almacena la contraseña en texto plano
• Se genera una firma digital (sign) para integridad

Control de Acceso

• Principio de menor privilegio
• Políticas granulares por funcionalidad
• Roles predefinidos para casos comunes

Auditoría

• Registro de timestamps de creación
• Rastreo de dispositivos cuando está habilitado
• Logs de todas las operaciones críticas

Recomendaciones

1. Revisar periódicamente las políticas asignadas
2. Desactivar usuarios en lugar de eliminarlos
3. Habilitar devicecheck para usuarios críticos
4. Limitar políticas de usuarios robot al mínimo necesario
5. Usar grupos para gestión eficiente de permisos

Campos Técnicos Adicionales

Para desarrolladores y administradores del sistema:

Metadatos del Sistema

{
  "timestamp": "2023-01-15T10:30:00Z",
  "hash": "$2b$10$...",
  "sign": "abc123def456...",
  "apikey": "api_key_for_robots_only"
}

Validaciones del Sistema

• Email único: No puede haber usuarios duplicados (excepto robots)
• Formato email: Validación de formato de correo electrónico
• Políticas válidas: Solo se aceptan políticas definidas en el sistema
• Roles válidos: admin, user, superadmin, robot

La gestión correcta de usuarios es fundamental para la seguridad y funcionamiento eficiente de ValerIA. Cada campo tiene un propósito específico en el ecosistema de permisos y control de acceso del sistema.