Autorización

La autorización define lo que los usuarios pueden y no pueden hacer tras la autenticación. Aptli combina dos capas independientes: derechos de administrador permisivos (lo que se puede hacer) y restricciones de roles restrictivas (lo que no se puede ver). Juntas, proporcionan a los administradores un control minucioso tanto sobre las capacidades como sobre la visibilidad de los datos.

Descripción general del modelo de autorización

El modelo de seguridad completo de Aptli consta de tres capas:

1. Autenticación: quién eres (tratado en la sección «Autenticación»)
2. Derechos de administrador: lo que PUEDES modificar (concesiones permisivas)
3. Restricciones de rol: lo que NO puedes ver (filtros restrictivos)

Todas las restricciones se aplican en el servidor: los datos no autorizados nunca se envían a tu navegador, independientemente de lo que intentes a través de la interfaz de usuario, la API o las exportaciones.

Este modelo ofrece una enorme flexibilidad sin renunciar a la seguridad.

Derechos de administrador (permisivos)

Los derechos de administrador otorgan permiso para modificar información o alterar el estado. Sin estos derechos, los usuarios solo pueden ver datos y editar su propio perfil.

Los derechos de administrador son una serie de opciones a la carta, específicas para cada usuario (user.admin). Cada entrada es un único nombre de derecho; no se agrupan en paquetes. Los derechos se conceden directamente al usuario, nunca se heredan de un rol.

Derechos de administrador comunes:

• usersUpdate: editar los perfiles de otros usuarios (nombre, cargo, división; NO correo electrónico ni contraseña)
• usersLogout: forzar el cierre de sesión o bloquear de forma permanente a los usuarios
• usersDelete: eliminar cuentas de usuario
• usersCreate: crear nuevos usuarios o recuperar cuentas eliminadas
• featureCreate, featureUpdate, featureDelete: modificar elementos del mapa (puntos, líneas, polígonos)
• allowCommits: publicar versiones del mapa en tiempo real (de lo contrario, la opción «Enviar» es una solicitud de revisión por parte del administrador)
• jobsCreate, jobsUpdate, jobsDelete: gestionar trabajos (unidades de trabajo planificadas)
• workOrdersCreate, workOrdersUpdate, workOrdersDelete: gestionar órdenes de trabajo
• reportsCreate, reportsUpdate, reportsDelete: enviar y gestionar informes de trabajo
• validationsCreate, validationsUpdate, validationsDelete: aprobación de control de calidad de los informes
• activitiesCreate, activitiesUpdate, activitiesDelete: mantener el catálogo de actividades (tipos de trabajo)
• projectsCreate, projectsUpdate, projectsDelete: gestionar proyectos
• transactionsCreate: crear transacciones de inventario (el libro mayor es de solo inserción; no hay derechos de actualización ni de eliminación)
• canFacilitatePickups: entregar materiales a una persona mediante un código QR de recogida en su nombre
• canTransferStock: trasladar existencias entre centros (los centros son los que realizan las transferencias, las personas son las que recogen)

Para enviar una solicitud de ayuda no se necesita ningún derecho: cualquier usuario autenticado puede realizarla. La disponibilidad del asistente de IA es una configuración válida para toda la implementación, no un derecho individual de cada usuario.

Derechos superiores (que prevalecen sobre todos los demás):

• appSettingSchemasModify: modificar la configuración a nivel de aplicación (dominios, tiempos de espera, seguridad)
• adminRightsModify: conceder derechos de administrador a otros usuarios
• viewDeleted: ver registros eliminados (casi universal, parcialmente anulado por restricciones de rol)

Comprobación de los derechos de administrador de un usuario:

1. Ve a Admin → Usuarios
2. Abre el perfil del usuario
3. La sección «Derechos de administrador» muestra todos los permisos concedidos

Restricciones de roles (restrictivas)

Los roles son conjuntos de restricciones que impiden ver y modificar registros con determinadas características. Un rol solo contiene un nombre y una lista de restricciones, nada más. Los roles no tienen miembros, propietario ni derechos de administrador. La pertenencia a un rol recae en el usuario: cada usuario tiene una lista de roles, y todas las restricciones de esos roles se aplican a ese usuario.

Para asignar un rol, añádelo al usuario desde su perfil (o configúralo como rol predeterminado para los nuevos usuarios). Para ver la lista de miembros de un rol, busca a los usuarios cuyos «roles» lo incluyan.

Componentes de un rol:

• Nombre: una etiqueta legible para los usuarios
• Restricciones del rol: filtros a nivel de campo que ocultan datos específicos

Los roles solo definen el ámbito de visibilidad y las restricciones. Nunca otorgan la capacidad de realizar ninguna acción; para eso están los derechos de administrador.

Estructura de las restricciones de un rol

Cada restricción define:

• Modelo (target_model) - Qué tipo de datos (usuario, característica, rol, etc.)
• Campo: en qué propiedad se va a filtrar (propietario, estado, categoría, campos personalizados)
• Comparación: cómo se va a realizar la coincidencia. Una de las siguientes: eq, ne, gt, gte, lt, lte, in, nin
• Valor de filtro: el valor con el que se debe realizar la coincidencia (un valor único o una matriz para in/nin)
• Permisos: una matriz con las operaciones que se deniegan cuando un registro cumple los criterios. Cada entrada es una de las siguientes: read, edit, create, delete. Incluir una operación aquí la bloquea; omitirla la permite.

La interfaz de usuario de administración de roles presenta estos elementos como columnas de modelo, acción y ruta.

Ejemplo de caso de uso: Separación de contratistas

Escenario: Evitar que el contratista A vea el trabajo del contratista B

Configuración:

1. Crear rol: «Contratista A»
2. Añadir restricción de rol:
   • Modelo: feature
   • Campo: owner
   • Comparación: eq
   • Valor de filtro: Contratista B
   • Permisos (denegados): read, edit, create, delete (los cuatro bloqueados)
3. Añadir el rol «Contratista A» a los usuarios del contratista A (desde el perfil de cada usuario)

Resultado:

• Los miembros del contratista A no pueden ver ninguna característica en la que el propietario sea «Contratista B»
• No solo se oculta en la interfaz de usuario: la API devuelve los datos como si los registros no existieran
• No se pueden ver accidentalmente mediante capturas de pantalla, llamadas a la API o exportaciones
• Se aplica íntegramente del lado del servidor

Casos de uso adicionales

Por fase de trabajo: Evitar que los trabajadores de campo vean los informes de validación de control de calidad:

Role: "Field Workers"
Restriction:
  Model: validation
  Field: status
  Comparison: ne
  Filter Value: "" (any value)
  Permissions (denied): read

Los trabajadores de campo no pueden ver las validaciones en absoluto.

Por tipo de activo: Separar los equipos de infraestructura (postes/conductos frente a equipos activos):

Role: "Civil Team"
Restriction:
  Model: feature
  Field: category
  Comparison: eq
  Filter Value: "Active Equipment"
  Permissions (denied): read, edit, create, delete

El equipo de obras civiles no puede ver ni modificar los elementos de equipo activo.

Por físico/lógico: Acceso a datos de oficina separado (relaciones de capacidad frente a ubicaciones de oficinas):

Role: "Capacity Analysts"
Restriction:
  Model: feature
  Field: layer
  Comparison: eq
  Filter Value: "Office Locations"
  Permissions (denied): edit, create, delete

Los analistas pueden ver las oficinas, pero no modificar sus ubicaciones (solo lectura; la lectura no está denegada).

Combinación de derechos de administrador + restricciones de rol

Comportamiento predeterminado: Todos los usuarios pueden verlo todo, pero no pueden modificar nada (sin derechos de administrador).

Añadir acceso de escritura con restricciones:

Ejemplo: Los trabajadores de campo pueden editar su propio trabajo, pero no el de los demás

Admin Rights:
  - reportsCreate: true
  - reportsUpdate: true

Role Restrictions:
  Model: report
  Field: submittedBy
  Comparison: ne
  Filter Value: [current user ID]
  Permissions (denied): edit

Resultado:

• Los trabajadores pueden crear informes (se les ha concedido el derecho de administrador)
• Los trabajadores pueden editar ÚNICAMENTE sus propios informes (la restricción de rol filtra los demás)
• No pueden ver ni modificar los informes de otros trabajadores

Aplicación del lado del servidor

Cómo funciona:

• Todas las consultas se filtran antes de que se devuelvan los datos
• Las restricciones de rol se aplican en el servidor (no se limitan a ocultar elementos en la interfaz de usuario)
• Los usuarios no pueden eludir estas restricciones mediante llamadas directas a la API, herramientas del navegador o exportaciones
• Los datos realmente no existen para los usuarios no autorizados

Implicaciones de seguridad:

• Una captura de pantalla de la pantalla de otra persona no servirá de nada (los datos no se cargarán para ti)
• No se pueden exportar datos restringidos (el servidor aplica los filtros)
• No se pueden «adivinar» los ID de los registros (se filtran antes de la búsqueda del ID)
• Los registros fuera de tus permisos se devuelven como «no encontrados», incluso si conoces el ID

Gestión de roles

Creación de roles:

1. Ve a Admin → Roles
2. Haz clic en «Crear rol»
3. Introduce el nombre del rol
4. Añade restricciones al rol (puede haber varias)
5. Guarda

Para crear un rol se requiere el derecho de administrador rolesCreate.

Edición de roles:

• Requiere el derecho de administrador rolesUpdate
• Se pueden modificar las restricciones
• Se puede eliminar un rol con rolesDelete (lo que libera a los miembros de dichas restricciones)

Los roles no tienen una lista de miembros que se pueda editar aquí: la pertenencia a un rol se establece en el usuario, no en el rol.

Pertenencia a un rol:

• La pertenencia se gestiona en el usuario (user.roles); añade o elimina roles del perfil de un usuario
• Los usuarios pueden pertenecer a varios roles (las restricciones se combinan)
• Al abandonar la organización: elimina todos los roles del usuario antes de borrar la cuenta

Personalización de la autorización para nuevos usuarios

Configuración de los ajustes de la aplicación (requiere appSettingSchemasModify):

1. Accede a «Ajustes de la aplicación»
2. «Roles predeterminados»: los roles que se asignan automáticamente a las nuevas cuentas
3. Guardar

No existe un ajuste de «derechos de administrador predeterminados»: los nuevos usuarios comienzan sin derechos de administrador. Concede los derechos a cada usuario desde su perfil una vez creada la cuenta.

Configuraciones habituales:

Trabajador de campo:

• Roles predeterminados: ["Trabajadores de campo"]
• Derechos de administrador concedidos al usuario tras la creación: reportsCreate

Coordinador de oficina:

• Roles predeterminados: ninguno
• Derechos de administrador concedidos al usuario tras la creación: workOrdersCreate, stockItemsCreate, stockItemsUpdate

Sin concesión automática (revisión manual):

• Roles predeterminados: ninguno
• Los administradores asignan manualmente los roles y derechos tras revisar la cuenta.

Visualización de los permisos efectivos

Para un usuario específico:

1. Accede al perfil del usuario
2. Sección «Derechos de administrador»: lo que PUEDE hacer
3. Sección «Roles»: lo que NO PUEDE ver (mediante restricciones)
4. La vista combinada muestra los permisos efectivos

Comprobación de permisos:

1. Inicia sesión como usuario (o suplantar su identidad con permisos de administrador)
2. Navega con normalidad
3. Los datos restringidos simplemente no aparecen
4. Las acciones que requieren derechos de administrador están desactivadas u ocultas

Prácticas recomendadas

Empieza con restricciones y concede permisos según sea necesario:

• Los nuevos usuarios reciben permisos mínimos
• Añade derechos de administrador según lo requieran los roles
• Es más fácil conceder que revocar (evita la «acumulación de permisos»)

Utiliza los roles para la visibilidad de los datos:

• Separa a los contratistas (evita la obtención de información sobre la competencia)
• Separar las fases de trabajo (control de calidad de los trabajadores de campo)
• Separar los tipos de activos (infraestructura de los equipos activos)

Utilizar los derechos de administrador para definir capacidades:

• Quién puede crear asignaciones
• Quién puede modificar el inventario
• Quién puede conceder permisos

Documentar la finalidad de cada rol:

• Nombre claro del rol («Contratista A» es mejor que «Rol 1»)
• La descripción explica las restricciones
• Ayuda a los futuros administradores a comprender la intención

Auditorías periódicas de permisos:

• Revisar trimestralmente los derechos de administrador de los usuarios
• Eliminar los derechos no utilizados (el usuario ha cambiado de rol)
• Comprobar la pertenencia a roles (usuarios que han abandonado la organización)

Supervisar los intentos de acceso:

• Registrar los intentos fallidos de autorización
• Un patrón de denegaciones indica que un usuario está intentando un acceso no autorizado
• Investigar y ajustar los permisos o formar al usuario

Principio del mínimo privilegio:

• Conceder los permisos mínimos necesarios para el desempeño de las funciones del puesto
• Acceso elevado temporal para proyectos (retirarlo después)
• Superprivilegios (adminRightsModify) solo para administradores de confianza