Documentación del Microservicio RBAC

Una guía completa para configurar, usar y administrar el servicio de Control de Acceso Basado en Roles para el ecosistema iRoyal.

Arquitectura y Propósito

Este microservicio funciona como la única fuente de verdad para la autorización dentro del ecosistema iRoyal. Su responsabilidad principal es gestionar roles y permisos, y proporcionar información sobre qué permisos tiene un usuario específico.

Importante: Este servicio NO maneja autenticación. Los usuarios se crean y autentican en auth.cloudhub.cl. Nuestro servicio solo asigna roles a esos usuarios existentes.

Flujo de Trabajo:

Usuario se registra/autentica en auth.cloudhub.cl
Auth Service consulta nuestro endpoint para obtener permisos del usuario
Auth Service incluye roles y permisos en el JWT
Aplicaciones usan el JWT para autorización

API Endpoints

Endpoint Principal - Obtener Permisos

GET/api/users/{userId}/permissions

Este es el endpoint que consume el Auth Service. Devuelve todos los roles y permisos de un usuario.

Respuesta Exitosa (200 OK)

{
  "roles": ["admin", "editor"],
  "permissions": [
    "read:contact",
    "create:contact",
    "update:contact",
    "read:invoice"
  ]
}

Ejemplo de Uso

curl http://localhost:3000/api/users/123e4567-e89b-12d3-a456-426614174000/permissions

CRUD de Permisos

Gestiona los permisos del sistema. Los permisos siguen el formato action:resource.

GET/api/admin/permissions

Obtener todos los permisos

curl http://localhost:3000/api/admin/permissions

POST/api/admin/permissions

Crear un nuevo permiso

curl -X POST http://localhost:3000/api/admin/permissions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "delete:invoice",
    "description": "Eliminar facturas"
  }'

PUT/api/admin/permissions/{id}

Actualizar un permiso existente

curl -X PUT http://localhost:3000/api/admin/permissions/permission-uuid \
  -H "Content-Type: application/json" \
  -d '{
    "name": "update:invoice",
    "description": "Actualizar facturas existentes"
  }'

DELETE/api/admin/permissions/{id}

Eliminar un permiso (solo si no está en uso)

curl -X DELETE http://localhost:3000/api/admin/permissions/permission-uuid

Panel de Administración Web

Además de los endpoints de API, el sistema incluye un panel web completo para gestionar permisos:

Acceso al Panel

URL: http://localhost:3000/admin

Funcionalidades

✅ Crear nuevos permisos con formato validado
✅ Ver lista de permisos existentes
✅ Eliminar permisos no utilizados
✅ Sugerencias de permisos comunes
✅ Crear roles y asignar permisos
✅ Asignar roles a usuarios

Flujo Recomendado

Crear Permisos → Pestaña "Crear Permiso"
Crear Roles → Pestaña "Crear Rol" (asignar permisos)
Asignar Roles → Pestaña "Asignar Roles" (a usuarios de auth.cloudhub.cl)

CRUD de Roles

Gestiona los roles del sistema y sus permisos asociados.

GET/api/admin/roles

Obtener todos los roles con sus permisos

curl http://localhost:3000/api/admin/roles

POST/api/admin/roles

Crear un nuevo rol con permisos

curl -X POST http://localhost:3000/api/admin/roles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "accountant",
    "description": "Contador del sistema",
    "permissionIds": ["perm-uuid-1", "perm-uuid-2"]
  }'

PUT/api/admin/roles/{id}

Actualizar un rol y sus permisos

curl -X PUT http://localhost:3000/api/admin/roles/role-uuid \
  -H "Content-Type: application/json" \
  -d '{
    "name": "senior_accountant",
    "description": "Contador senior con más permisos",
    "permissionIds": ["perm-uuid-1", "perm-uuid-2", "perm-uuid-3"]
  }'

DELETE/api/admin/roles/{id}

Eliminar un rol (solo si no está asignado a usuarios)

curl -X DELETE http://localhost:3000/api/admin/roles/role-uuid

Gestión de Usuarios

Asigna y gestiona roles de usuarios que ya existen en auth.cloudhub.cl.

GET/api/admin/users

Listar todos los usuarios con roles asignados

curl http://localhost:3000/api/admin/users

GET/api/admin/users/{userId}

Obtener información específica de un usuario

curl http://localhost:3000/api/admin/users/user-uuid-here

POST/api/admin/users

Asignar roles a un usuario nuevo en RBAC

curl -X POST http://localhost:3000/api/admin/users \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-uuid-from-auth-service",
    "roleIds": ["role-uuid-1", "role-uuid-2"]
  }'

PUT/api/admin/users/{userId}/roles

Actualizar roles de un usuario existente

curl -X PUT http://localhost:3000/api/admin/users/user-uuid/roles \
  -H "Content-Type: application/json" \
  -d '{
    "roleIds": ["role-uuid-1", "role-uuid-3"]
  }'

DELETE/api/admin/users/{userId}

Eliminar todos los roles de un usuario

curl -X DELETE http://localhost:3000/api/admin/users/user-uuid

Estadísticas del Sistema

GET/api/admin/stats

Obtener estadísticas generales del sistema RBAC

curl http://localhost:3000/api/admin/stats

Respuesta de Ejemplo

{
  "stats": {
    "roles": 5,
    "permissions": 12,
    "users_with_roles": 8,
    "role_permission_assignments": 25,
    "user_role_assignments": 15
  },
  "popularRoles": [
    {
      "name": "admin",
      "description": "Acceso total al sistema",
      "user_count": 3
    }
  ],
  "popularPermissions": [
    {
      "name": "read:contact",
      "description": "Ver información de contactos",
      "role_count": 4
    }
  ]
}

Configuración de la Base de Datos

1. Variable de Entorno

Crea un archivo .env.local en la raíz del proyecto:

RBAC_DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"

2. Ejecutar Scripts SQL

Conéctate a tu base de datos Neon y ejecuta estos scripts en orden:

scripts/migrations/0001_rbac_initial_schema.sql - Crea las tablas
scripts/migrations/0002_rbac_seed_data.sql - Inserta datos iniciales

3. Estructura de Datos

El sistema utiliza las siguientes tablas principales:

roles - Define los roles del sistema (admin, editor, etc.)
permissions - Lista de permisos disponibles (read:contact, create:invoice, etc.)
role_permissions - Relaciona roles con permisos
user_roles - Asigna roles a usuarios (usando UUIDs de auth.cloudhub.cl)

Panel de Administración

El servicio incluye un panel web completo para administrar roles y usuarios:

Acceso al Panel

Una vez que el servicio esté corriendo:

Dashboard: http://localhost:3000/dashboard
Administración: http://localhost:3000/admin
Documentación: http://localhost:3000/documentacion

Funcionalidades del Panel

Dashboard

• Ver estadísticas generales
• Explorar roles y permisos
• Revisar usuarios con roles
• Interfaz de solo lectura

Administración

• Crear nuevos roles
• Asignar permisos a roles
• Asignar roles a usuarios
• Gestión completa del sistema

Flujo de Trabajo Típico

Un usuario se registra en auth.cloudhub.cl
El administrador va al panel de Administración
Busca el usuario por su UUID y le asigna roles apropiados
El usuario ahora tiene permisos que se reflejan en su JWT

Instalación y Ejecución

1. Instalar Dependencias

pnpm install

2. Configurar Base de Datos

Ejecuta los scripts SQL en tu base de datos Neon.

3. Iniciar el Servicio

pnpm dev

El servicio estará disponible en http://localhost:3000

4. Verificar Funcionamiento

Prueba el endpoint principal con el usuario de prueba:

curl http://localhost:3000/api/users/00000000-0000-0000-0000-000000000001/permissions

Herramientas de Diagnóstico

El servicio incluye herramientas de diagnóstico para solucionar problemas:

Página de Debug

Accede a http://localhost:3000/debug para:

Verificar el estado de la base de datos
Probar usuarios específicos
Crear usuarios de prueba
Ver información detallada de asignaciones

Endpoints de Debug

/api/debug/database - Estado completo de la BD

/api/debug/user/{userId} - Info detallada de usuario

/api/debug/create-test-user - Crear usuario de prueba

Ejemplos Prácticos de Uso

Aquí tienes algunos ejemplos prácticos de cómo usar la API completa:

1. Configuración Inicial del Sistema

Crear permisos básicos para un CRM:

# Crear permisos básicos
curl -X POST http://localhost:3000/api/admin/permissions \
  -H "Content-Type: application/json" \
  -d '{"name": "create:contact", "description": "Crear contactos"}'

curl -X POST http://localhost:3000/api/admin/permissions \
  -H "Content-Type: application/json" \
  -d '{"name": "read:contact", "description": "Ver contactos"}'

curl -X POST http://localhost:3000/api/admin/permissions \
  -H "Content-Type: application/json" \
  -d '{"name": "update:contact", "description": "Editar contactos"}'

curl -X POST http://localhost:3000/api/admin/permissions \
  -H "Content-Type: application/json" \
  -d '{"name": "delete:contact", "description": "Eliminar contactos"}'

2. Crear Roles con Permisos

Crear un rol de "Editor" con permisos específicos:

# Primero obtener los IDs de los permisos
curl http://localhost:3000/api/admin/permissions

# Luego crear el rol con esos IDs
curl -X POST http://localhost:3000/api/admin/roles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Puede crear y editar contactos",
    "permissionIds": [
      "permission-uuid-create-contact",
      "permission-uuid-read-contact", 
      "permission-uuid-update-contact"
    ]
  }'

3. Asignar Roles a Usuarios

Asignar el rol de editor a un usuario específico:

# Obtener los IDs de los roles disponibles
curl http://localhost:3000/api/admin/roles

# Asignar roles al usuario
curl -X POST http://localhost:3000/api/admin/users \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "roleIds": ["role-uuid-editor"]
  }'

4. Verificar Permisos de Usuario

Verificar qué permisos tiene un usuario (endpoint principal):

curl http://localhost:3000/api/users/123e4567-e89b-12d3-a456-426614174000/permissions

# Respuesta esperada:
{
  "roles": ["editor"],
  "permissions": [
    "create:contact",
    "read:contact",
    "update:contact"
  ]
}

5. Actualizar Permisos de un Rol

Agregar más permisos a un rol existente:

curl -X PUT http://localhost:3000/api/admin/roles/role-uuid-editor \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Puede crear, editar y eliminar contactos",
    "permissionIds": [
      "permission-uuid-create-contact",
      "permission-uuid-read-contact",
    "name": "editor",
    "description": "Puede crear, editar y eliminar contactos",
    "permissionIds": [
      "permission-uuid-create-contact",
      "permission-uuid-read-contact",
      "permission-uuid-update-contact",
      "permission-uuid-delete-contact"
    ]
  }'

6. Monitorear el Sistema

Obtener estadísticas para monitoreo:

curl http://localhost:localhost:3000/api/admin/stats