Roles y permisos (RBAC)

Descripción general

Cada solicitud autenticada se comprueba contra el rol del llamador en el tenant objetivo. Los permisos siguen un patrón resource:action (p. ej. agent:write). Los administradores de plataforma omiten el ámbito del tenant y tienen todos los permisos. Los roles con ámbito de tenant se asignan por tenant, por lo que un usuario puede ser auditor en un tenant y tenant_admin en otro.

La caché de permisos tiene un TTL de 60 segundos con degradación elegante — si la base de datos no está temporalmente disponible, se sirven permisos obsoletos en lugar de denegar el acceso.

Roles integrados

ShieldAgent incluye seis roles del sistema. Los roles personalizados aún no son compatibles — las asignaciones usan estos roles integrados.

Matriz de permisos

La matriz siguiente muestra cada permiso y qué roles lo incluyen. platform_admin y tenant_admin tienen todos los permisos y se omiten para mayor legibilidad.

Requisitos de autenticación de endpoints

Cada endpoint con ámbito de tenant requiere un JWT válido más el permiso listado. El middleware valida tanto la pertenencia al tenant como el permiso específico antes de que se ejecute el manejador. Se devuelve un 403 Forbidden si la comprobación falla.

Uso del middleware

Los manejadores de rutas adjuntan comprobaciones RBAC como hooks preHandler de Fastify. Hay dos variantes disponibles:

fastify.get(
  '/tenants/:tenantId/agents',
  { preHandler: [authenticate, rbac.requireTenantPermission('agent:read')] },
  async (request, reply) => { /* handler */ }
);

fastify.get(
  '/policy-templates',
  { preHandler: [authenticate, rbac.requirePermission('policy:read')] },
  async (request, reply) => { /* handler */ }
);

Endpoints públicos

Un pequeño número de endpoints omiten la autenticación por completo:

Asignación de roles

Los roles se asignan por usuario por tenant mediante la tabla user_roles. Un usuario puede tener diferentes roles en diferentes tenants. Las asignaciones rastrean quién otorgó el rol y admiten expiración opcional.

// Assign a role via the API
PATCH /tenants/:tenantId/users/:userId
{
  "role": "security_operator"
}
// Requires: user:write permission

Los valores de rol heredados (admin, tenant) se normalizan automáticamente a sus equivalentes RBAC (platform_admin, tenant_admin) a nivel de middleware.