PANEL_BASES_ANEXO24/docs/USUARIOS.md

Sistema de Gestión de Usuarios y Permisos

Este sistema permite administrar usuarios y controlar qué bases de datos puede ver cada usuario.

Características

• ✅ Autenticación con JWT
• ✅ Roles de usuario (Admin y Usuario normal)
• ✅ Permisos granulares por base de datos
• ✅ Gestión completa de usuarios (CRUD)
• ✅ Sesiones seguras con cookies HTTP-only
• ✅ Validación de contraseñas fuertes

Instalación

1. Instalar dependencias

npm install bcrypt jsonwebtoken pg @types/pg @types/bcrypt @types/jsonwebtoken

2. Configurar PostgreSQL

Ejecuta el script SQL en tu base de datos PostgreSQL:

psql -h 10.0.20.152 -U postgres -d CONTROLDESK -f database/schema.sql

O manualmente desde pgAdmin o DBeaver.

3. Generar hash de contraseña para admin

node scripts/generate-password-hash.js

Copia el hash generado y actualiza el script database/schema.sql con la contraseña real.

4. Configurar variables de entorno

Copia .env.example a .env y actualiza los valores:

cp .env.example .env

Asegúrate de cambiar el JWT_SECRET por un valor seguro y aleatorio.

Uso

Primer Login

1. Ve a http://localhost:5173/login
2. Usuario: admin
3. Contraseña: Admin123! (o la que hayas configurado)

Gestión de Usuarios (Solo Admins)

1. Inicia sesión como admin
2. Ve a "Gestión de Usuarios" en el sidebar
3. Podrás:
   • Crear nuevos usuarios
   • Editar usuarios existentes
   • Activar/desactivar usuarios
   • Eliminar usuarios
   • Asignar permisos de bases de datos

Asignar Permisos

1. En la página de "Gestión de Usuarios", haz clic en el ícono de candado 🔒 del usuario
2. Verás la lista de todas las bases de datos disponibles
3. Haz clic en "Sin Acceso" para otorgar acceso a una base de datos
4. Haz clic en "Con Acceso" para revocar el acceso

Nota: Los usuarios con rol de Administrador tienen acceso a todas las bases de datos automáticamente.

Permisos

Cada usuario puede tener los siguientes permisos por base de datos:

• puede_ver: Permite ver la base de datos en el panel
• puede_descargar_backup: Permite descargar archivos de backup (futuro)
• puede_restaurar: Permite ejecutar restauraciones (futuro)

Actualmente, el sistema filtra las bases de datos que el usuario puede ver en:

• Panel principal (dashboard)
• Alertas críticas

Roles

Administrador

• Acceso completo a todas las bases de datos
• Puede gestionar usuarios y permisos
• Puede ver la sección "Gestión de Usuarios"

Usuario Normal

• Solo ve las bases de datos que le han sido asignadas
• No puede gestionar usuarios
• No tiene acceso a la sección de administración

Seguridad

Contraseñas

Las contraseñas deben cumplir con los siguientes requisitos:

• Mínimo 8 caracteres
• Al menos una mayúscula
• Al menos una minúscula
• Al menos un número
• Al menos un carácter especial (!@#$%^&*(),.?":{}|<>)

Sesiones

• Las sesiones usan JWT (JSON Web Tokens)
• Los tokens se almacenan en cookies HTTP-only (no accesibles desde JavaScript)
• Los tokens expiran después de 7 días
• En producción, las cookies usan el flag secure (solo HTTPS)

Estructura de Base de Datos

Tabla: usuarios

id              SERIAL PRIMARY KEY
username        VARCHAR(50) UNIQUE NOT NULL
email           VARCHAR(100) UNIQUE NOT NULL
password_hash   VARCHAR(255) NOT NULL
nombre_completo VARCHAR(100)
activo          BOOLEAN DEFAULT true
es_admin        BOOLEAN DEFAULT false
fecha_creacion  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
ultimo_acceso   TIMESTAMP

Tabla: usuario_base_datos

id                      SERIAL PRIMARY KEY
usuario_id              INTEGER NOT NULL (FK a usuarios)
base_datos_nombre       VARCHAR(255) NOT NULL
puede_ver               BOOLEAN DEFAULT true
puede_descargar_backup  BOOLEAN DEFAULT false
puede_restaurar         BOOLEAN DEFAULT false
fecha_asignacion        TIMESTAMP DEFAULT CURRENT_TIMESTAMP

Tabla: sesiones

id                SERIAL PRIMARY KEY
usuario_id        INTEGER NOT NULL (FK a usuarios)
token             VARCHAR(255) UNIQUE NOT NULL
ip_address        VARCHAR(50)
user_agent        TEXT
fecha_creacion    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
fecha_expiracion  TIMESTAMP NOT NULL
activa            BOOLEAN DEFAULT true

API

Rutas de Autenticación

• GET /login - Página de inicio de sesión
• POST /login?/login - Procesar inicio de sesión
• GET /logout - Cerrar sesión

Rutas de Usuarios (Solo Admins)

• GET /usuarios - Página de gestión de usuarios
• POST /usuarios?/createUser - Crear usuario
• POST /usuarios?/updateUser - Actualizar usuario
• POST /usuarios?/deleteUser - Eliminar usuario
• POST /usuarios?/managePermissions - Asignar/revocar permisos
• GET /usuarios/api/permissions?userId=X - Obtener permisos de un usuario

Troubleshooting

Error: "Could not connect to PostgreSQL"

Verifica que:

1. PostgreSQL esté corriendo en el servidor
2. Las credenciales en .env sean correctas
3. El firewall permita conexiones al puerto 5432
4. La base de datos CONTROLDESK exista

Error: "Invalid token"

1. Cierra sesión y vuelve a iniciar sesión
2. Verifica que JWT_SECRET sea consistente
3. Limpia las cookies del navegador

Error: "User not found"

1. Verifica que hayas ejecutado el script SQL
2. Revisa que el usuario admin se haya creado correctamente:

   SELECT * FROM usuarios WHERE username = 'admin';
   

No puedo ver algunas bases de datos

Si eres usuario normal (no admin):

1. Contacta al administrador para que te asigne permisos
2. Verifica en la base de datos:

   SELECT * FROM usuario_base_datos WHERE usuario_id = TU_ID;
   

Futuras Mejoras

• Recuperación de contraseña por email
• Autenticación de dos factores (2FA)
• Registro de auditoría de acciones
• Permisos más granulares (lectura, escritura, eliminación)
• Grupos de usuarios
• API REST para integraciones
• Notificaciones por email de cambios de permisos

Soporte

Para reportar problemas o sugerencias, contacta al equipo de desarrollo.