Permisos y roles

Canopy utiliza un modelo de permisos de tres capas que combina el control de acceso basado en roles a nivel de aplicación con roles de partes interesadas específicos por tarjeta. Esta página explica el diseño, cuándo usar cada capa y cómo las capas se combinan para formar permisos efectivos.

¿Por qué tres capas?

La Arquitectura Empresarial es inherentemente transversal. Una tarjeta determinada — por ejemplo, una Application — podría ser:

• Solo lectura para la mayoría de los usuarios (los observadores ven el inventario pero no pueden editar)
• Editable por el equipo general de AE (los miembros pueden actualizar cualquier tarjeta)
• Gestionada por una persona específica responsable de esa aplicación (el Propietario técnico de la aplicación puede editar y aprobar el estado, incluso si no tiene derechos de edición en toda la organización)
• Totalmente controlada por los administradores (que pueden hacer cualquier cosa)

Un sistema de roles plano cubre los tres primeros casos pero falla en el cuarto: o bien se otorgan derechos de edición en toda la organización (demasiado amplio) o no se otorga nada (demasiado restrictivo). La capa de partes interesadas resuelve esto concediendo permisos por tarjeta a personas designadas.

Capa 1 — Roles de aplicación

Los roles de aplicación se asignan a usuarios y se aplican en toda la plataforma. Se definen y gestionan en Administración → Usuarios y roles.

Cada rol lleva un conjunto de permisos en JSON. Los roles integrados son:

Rol	Clave	Alcance
Administrador	admin	Comodín {"*": true} — sin restricciones
Administrador BPM	bpm_admin	BPM completo + inventario completo, sin admin.*
Miembro	member	Inventario completo + edición BPM, sin admin.*
Observador	viewer	Solo lectura en todos los dominios

Se pueden crear roles personalizados con cualquier combinación de las claves de permiso disponibles, agrupadas en dominios como inventory.*, reports.*, bpm.*, ppm.*, grc.*, todos.*, admin.*.

Use los roles de aplicación cuando necesite controlar lo que puede hacer una categoría de usuarios en toda la plataforma.

Capa 2 — Roles de partes interesadas

Los roles de partes interesadas se asignan a usuarios en tarjetas específicas. Cada tipo de tarjeta define su propio conjunto de definiciones de roles de partes interesadas (por ejemplo, las tarjetas Application tienen «Propietario técnico de la aplicación», «Propietario de negocio de la aplicación», «Custodio de datos»). Estos se configuran en Administración → Metamodelo → [tipo] → Roles de partes interesadas.

Cada definición de rol de parte interesada lleva un conjunto de permisos a nivel de tarjeta — cosas como card.edit, card.approve, card.manage_relations. Cuando se añade a un usuario como parte interesada en una tarjeta, obtiene esos permisos solo en esa tarjeta.

Use los roles de partes interesadas cuando la propiedad o la responsabilidad sea específica de una tarjeta: el propietario de una aplicación concreta debe poder gestionarla sin obtener derechos de edición sobre las otras 500 aplicaciones.

Capa 3 — Permisos efectivos

Cuando un usuario intenta realizar una acción sobre una tarjeta, el sistema calcula sus permisos efectivos combinando:

1. Sus permisos de rol de aplicación (mapeados de claves a nivel de plataforma a claves a nivel de tarjeta)
2. Todos los permisos de roles de partes interesadas que tiene en esa tarjeta concreta

El resultado es la unión de ambos conjuntos. Un usuario que es Observador (en toda la plataforma) pero Propietario técnico de la aplicación en una tarjeta puede editar esa tarjeta, porque el rol de parte interesada concede card.edit aunque el rol de Observador no lo haga.

Los permisos efectivos del usuario actual sobre una tarjeta determinada se exponen en GET /cards/{id}/effective-permissions y controlan todos los controles de edición, aprobación y eliminación en la interfaz.

El comodín de administrador

El rol Administrador usa {"*": true} como su conjunto de permisos. Esto se evalúa como «permitir todo» — incluyendo permisos que no existían cuando se creó el rol. Esto significa que los nuevos módulos y las nuevas claves de permiso están disponibles automáticamente para los administradores sin ninguna actualización de rol.

Ningún otro rol integrado usa el comodín. Al crear roles personalizados, use claves de permiso explícitas en lugar de comodines — esto hace que el alcance del rol sea auditable y evita concesiones accidentales excesivas.

Estructura de las claves de permiso

Todas las claves de permiso siguen el patrón dominio.acción:

• inventory.view — leer tarjetas
• inventory.edit — actualizar tarjetas
• inventory.create — crear tarjetas
• admin.metamodel — gestionar tipos de tarjeta y tipos de relación
• admin.impersonate — actuar temporalmente como un rol diferente (véase Suplantación de roles)
• bpm.approve — aprobar versiones de flujo de proceso BPMN
• todos.view / todos.create / todos.manage — acceder y gestionar tareas pendientes
• risks.manage — crear y actualizar entradas del registro de riesgos

La lista completa de claves válidas está en backend/app/core/permissions.py, que es la única fuente de verdad. Las nuevas claves de permiso deben añadirse allí antes de que puedan concederse a cualquier rol.

Patrones habituales

Restringir un módulo a un equipo: Cree un rol personalizado con solo los permisos ppm.* y inventory.view. Asígnelo al equipo de gestión del portafolio de proyectos. Podrán trabajar en PPM pero no podrán editar el inventario principal.

Conceder derechos de aprobación sin derechos de edición: Asigne a una parte interesada de negocio el rol de «Propietario de negocio de la aplicación» en tarjetas Application específicas. Configure ese rol para incluir card.approval_status pero no card.edit. Podrá aprobar tarjetas que el equipo de AE ha rellenado, pero no podrá modificar los datos.

Acceso de emergencia para un administrador: El comodín de administrador significa que cualquier permiso futuro — incluyendo los añadidos por extensiones o versiones futuras — se concede automáticamente. Use el rol Administrador solo para los usuarios que genuinamente necesiten acceso sin restricciones.

Probar como un rol específico: Los usuarios con admin.impersonate pueden cambiar a cualquier rol que no sea administrador desde el menú de usuario (Ver como rol…) para verificar exactamente qué puede ver y hacer ese rol — sin necesidad de crear una cuenta de prueba separada. La sesión de suplantación es solo JWT y no deja ningún rastro en la cuenta subyacente. Consulte Suplantación de roles para el flujo de trabajo completo.

Véase también

• Usuarios y roles — crear y editar roles de aplicación
• Administración del metamodelo — configurar roles de partes interesadas por tipo de tarjeta
• Detalle de tarjeta: pestaña Partes interesadas — asignar partes interesadas a una tarjeta