Ir al contenido

Roles y control de acceso

El modelo de autorización de Pier tiene dos ámbitos. Cada usuario tiene un rol global, y además puede tener un rol de proyecto en cada proyecto del que sea miembro. La mayoría de los endpoints comprueban uno u otro; unos pocos de gran impacto están reservados para el Owner.

Un rol global se almacena en el registro del usuario y acompaña a cada solicitud autenticada. Hay tres, ordenados de mayor a menor privilegio.

Rol Qué puede hacer
Owner Todo lo que puede hacer Admin, además de los controles exclusivos del Owner: cambiar los roles globales de otros usuarios, eliminar/promover Admins, las concesiones de federación y la malla WireGuard. El primer usuario creado en la configuración es el Owner. Siempre se requiere al menos un Owner activo.
Admin Gestionar usuarios (invitar, editar, eliminar a quienes no sean Owner), gestionar servidores, ver las métricas del sistema y el registro de auditoría, crear proyectos y operar recursos a nivel de Docker (contenedores, imágenes, stacks de compose, redes, registros). Omite la pertenencia a proyectos — un Admin llega a todos los proyectos.
User Un miembro normal. Solo ve los proyectos de los que es miembro explícito, además de los endpoints globales de solo lectura (lista de servidores, métricas del sistema). No puede crear proyectos ni gestionar usuarios.

Los roles globales Owner y Admin omiten las comprobaciones de pertenencia a proyectos — se tratan como Admin de proyecto en cada proyecto.

Un rol de proyecto se concede mediante la pertenencia al proyecto (la tabla project_members) y limita el alcance de un User a un único proyecto sin otorgarle poder global. Hay tres.

Rol Qué puede hacer dentro del proyecto
Admin Todo lo que puede hacer Editor, además de gestionar la pertenencia al proyecto (añadir/eliminar miembros, cambiar sus roles).
Editor Desplegar y volver a desplegar servicios, cambiar variables de entorno, dominios y ajustes, reiniciar.
Viewer Solo lectura: configuraciones, registros, métricas e historial de despliegues.

Cada proyecto conserva al menos un Admin de proyecto: Pier se niega a degradar o eliminar al último.

Dos mecanismos imponen los roles:

  • Guardas globales a nivel de enrutador. Grupos enteros de rutas se sitúan detrás de una capa de middleware. require_global_admin controla la gestión de usuarios, las operaciones del demonio de Docker, los stacks de compose, los registros, el registro de auditoría y las mutaciones de servidores. require_global_owner controla los cambios de rol global (PUT /users/{id}/role), la malla y las concesiones de federación.
  • Comprobaciones de proyecto dentro del handler. Las rutas con ámbito de proyecto (recursos, despliegues, env, copias de seguridad) llaman a enforce_project_role / enforce_resource_role al principio del handler, resolviendo el recurso hasta su proyecto y exigiendo un rol de proyecto mínimo.

Un mapa conciso de las acciones comunes:

Acción Rol mínimo
Explorar el catálogo / ver los servicios de un proyecto Viewer (proyecto)
Desplegar o volver a desplegar un servicio, editar env/dominios Editor (proyecto)
Añadir o eliminar un miembro del proyecto Admin (proyecto)
Crear un proyecto nuevo Admin (global)
Invitar o eliminar usuarios, ver el registro de auditoría Admin (global)
Promover a un usuario a Admin, o cambiar cualquier rol global Owner (global)
Gestionar las concesiones de federación o la malla WireGuard Owner (global)