Roles y Permisos (RBAC)

Auris implementa el control de acceso basado en roles (RBAC) con un modelo de resolución de permisos de tres estados: los permisos pueden ser explícitamente ALLOW (permitir), explícitamente DENY (denegar) o INHERIT (heredar del valor predeterminado del rol). Las anulaciones de permisos a nivel de usuario tienen precedencia sobre los permisos a nivel de rol, permitiendo excepciones detalladas sin crear roles dedicados.

Formato de Permisos

Todos los permisos en Auris siguen el patrón acción:recurso:

manage:users          view:invoices         create:tickets
edit:roles            approve:expenses      delete:documents
assign:tickets        sign:interventions    export:reports

El componente acción describe qué habilita el permiso. Acciones comunes: view, create, edit, delete, manage, approve, assign, export, sign, generate.

El componente recurso describe la entidad o función a la que se accede. Los recursos corresponden a módulos en tu aplicación.

Existe un permiso especial — admin:all — que otorga acceso sin restricciones a todos los recursos cuando lo tiene un rol. Se asigna al rol integrado Administrador.

Creación de Roles

Desde la Consola

1. Ve a Consola → Roles → Crear Rol
2. Introduce un nombre (ej. Gestor de Facturas), descripción opcional y elige un color para la insignia del rol
3. El rol se crea sin permisos. Configura los permisos en la página de detalle del rol.

Desde la API

// Usando el Management Client de Auris
const management = await createManagementClient({ ... })
const rol = await management.roles.create({
  name: 'Gestor de Facturas',
  description: 'Puede crear y ver facturas pero no eliminarlas',
  color: '#3b82f6',
})

Configuración de Permisos

Categorías de Permisos

El editor de permisos de la Consola organiza los permisos en 10 categorías:

Establecer Permisos en un Rol

En la Consola, cada permiso tiene un selector de tres estados en la página de detalle del rol:

• ALLOW — El permiso se concede a los usuarios con este rol
• DENY — El permiso se deniega explícitamente, anulando ALLOW heredado de otros roles
• INHERIT — El rol ni concede ni deniega este permiso (predeterminado)

A un usuario se le concede un permiso si cualquiera de sus roles lo tiene configurado como ALLOW y ninguno de sus roles lo tiene configurado como DENY.

Desde la API

Asignación de Roles a Usuarios

Los roles se asignan a usuarios en la Consola (Usuarios → [Usuario] → pestaña Roles) o a través de la API:

Los usuarios pueden tener múltiples roles. Los permisos de todos los roles se fusionan. Si algún rol tiene DENY para un permiso, esto anula ALLOW de otros roles.

Anulaciones de Permisos a Nivel de Usuario

Los usuarios individuales pueden tener permisos establecidos directamente, independientemente de sus roles. Las anulaciones de usuario tienen precedencia sobre todos los permisos de rol:

• Una ALLOW a nivel de usuario concede el permiso aunque ningún rol lo otorgue
• Una DENY a nivel de usuario bloquea el permiso aunque un rol otorgue ALLOW

Consola: Usuarios → [Usuario] → pestaña Permisos → Añadir Anulación

Verificación de Permisos

Del Lado del Servidor (Rutas de API)

Usa el helper requirePermission() para aplicar permisos en rutas de API:

// app/api/invoices/route.ts
import { requirePermission } from '@auris/nextjs/server'
 
const config = {
  domain: process.env.NEXT_PUBLIC_AURIS_DOMAIN!,
  clientId: process.env.NEXT_PUBLIC_AURIS_CLIENT_ID!,
}
 
export const GET = requirePermission('view:invoices', config, async (req, { session }) => {
  // Solo se alcanza si el usuario tiene el permiso view:invoices
  const facturas = await obtenerFacturas(session.user.id)
  return Response.json(facturas)
})
 
export const POST = requirePermission('create:invoices', config, async (req, { session }) => {
  const body = await req.json()
  const factura = await crearFactura(body, session.user.id)
  return Response.json(factura, { status: 201 })
})

// Verificar un permiso en un Server Component
import { checkPermission } from '@auris/nextjs/server'
 
export default async function SeccionAdmin() {
  const puedeGestionarUsuarios = await checkPermission('manage:users')
 
  if (!puedeGestionarUsuarios) {
    return <p>No tienes permiso para gestionar usuarios.</p>
  }
 
  return <PanelGestionUsuarios />
}

Del Lado del Cliente (Componentes React)

import { useCheckPermission, usePermissions } from '@auris/react'
 
// Verificar un único permiso
function AccionesFactura() {
  const { allowed: puedeCrear, isLoading } = useCheckPermission('create:invoices')
  const { allowed: puedeEliminar } = useCheckPermission('delete:invoices')
 
  if (isLoading) return null
 
  return (
    <div>
      {puedeCrear && <button>Nueva Factura</button>}
      {puedeEliminar && <button>Eliminar Seleccionadas</button>}
    </div>
  )
}
 
// Verificar múltiples permisos a la vez
function NavDashboard() {
  const { has, hasAll, hasAny } = usePermissions([
    'view:invoices',
    'view:quotes',
    'manage:users',
    'view:billing',
  ])
 
  return (
    <nav>
      {has('view:invoices') && <a href="/invoices">Facturas</a>}
      {has('view:quotes') && <a href="/quotes">Presupuestos</a>}
      {has('manage:users') && <a href="/users">Usuarios</a>}
      {has('view:billing') && <a href="/billing">Facturación</a>}
      {hasAll(['view:invoices', 'view:quotes']) && <a href="/documents">Todos los Documentos</a>}
      {hasAny(['manage:users', 'manage:roles']) && <a href="/es/admin">Administración</a>}
    </nav>
  )
}

import { PermissionGate } from '@auris/react'
 
// Renderizar condicionalmente la interfaz según el permiso
function PaginaFactura() {
  return (
    <div>
      <h1>Facturas</h1>
 
      {/* Solo se renderiza si el usuario tiene create:invoices */}
      <PermissionGate permission="create:invoices">
        <button>Nueva Factura</button>
      </PermissionGate>
 
      {/* Renderizar un fallback para usuarios no autorizados */}
      <PermissionGate
        permission="delete:invoices"
        fallback={<span>Acceso de solo lectura</span>}
      >
        <button>Eliminar Seleccionadas</button>
      </PermissionGate>
    </div>
  )
}

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.tudominio.com', clientId: 'tu-client-id' })
 
// Verificar un único permiso
const resultado = await auris.permissions.checkOne('manage:users')
console.log(resultado.allowed) // boolean
 
// Verificar múltiples permisos a la vez
const resultados = await auris.permissions.check([
  'view:invoices',
  'create:invoices',
  'delete:invoices',
])
 
resultados.forEach((resultado) => {
  console.log(`${resultado.permission}: ${resultado.allowed}`)
})
 
// Obtener todos los permisos que tiene el usuario actual
const todosLosPermisos = await auris.permissions.listUserPermissions()
console.log(todosLosPermisos) // string[] — ej., ['view:invoices', 'create:quotes', ...]

API de Permisos

Orden de Resolución de Permisos

Cuando Auris resuelve si un usuario tiene un permiso específico, sigue esta precedencia:

1. DENY de anulación a nivel de usuario — Si existe, el permiso es denegado. No se evalúa más.
2. ALLOW de anulación a nivel de usuario — Si existe (y no hay DENY), el permiso es concedido.
3. Permisos de rol — Si algún rol tiene ALLOW y ningún rol tiene DENY, el permiso es concedido.
4. Denegación implícita — Si ninguna regla concede el permiso, es denegado.

DENY de anulación de usuario  →  DENEGADO (se detiene aquí)
ALLOW de anulación de usuario →  CONCEDIDO (se detiene aquí)
DENY de cualquier rol         →  DENEGADO (se detiene aquí)
ALLOW de cualquier rol        →  CONCEDIDO
Sin coincidencia              →  DENEGADO

Permisos con Alcance de Aplicación

Los permisos pueden, opcionalmente, tener alcance para una aplicación específica. Cuando se incluye un applicationId en una verificación de permisos, Auris evalúa los permisos dentro del contexto de esa aplicación — útil para tenants con múltiples aplicaciones donde los roles pueden diferir por aplicación.

const resultado = await fetch('/api/roles/check', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    permissions: ['view:invoices', 'create:invoices'],
    applicationId: 'app-id-de-la-app-de-facturacion',
  }),
})

Guías Relacionadas

• Autorización de Grano Fino — Control de acceso a nivel de objeto más allá de los roles
• Claims JWT Personalizados — Incrustar datos de roles o permisos en los access tokens
• Credenciales M2M (Client Credentials) — Autorización para llamadas servidor a servidor