Ruoli e Permessi (RBAC)

Auris implementa il controllo degli accessi basato sui ruoli (RBAC) con un modello di risoluzione dei permessi a tre stati: i permessi possono essere esplicitamente ALLOW (consentiti), esplicitamente DENY (negati) o INHERIT (ereditati dal default del ruolo). Le sovrascritture a livello utente hanno precedenza sui permessi a livello di ruolo, consentendo eccezioni granulari senza dover creare ruoli dedicati.

Formato dei Permessi

Tutti i permessi in Auris seguono il pattern azione:risorsa:

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

Il componente azione descrive cosa abilita il permesso. Azioni comuni: view, create, edit, delete, manage, approve, assign, export, sign, generate.

Il componente risorsa descrive l’entità o funzionalità a cui si accede. Le risorse corrispondono ai moduli della tua applicazione.

Esiste un permesso speciale — admin:all — che concede accesso illimitato a tutte le risorse. È assegnato al ruolo Amministratore predefinito.

Creare Ruoli

Tramite la Console

1. Vai su Console → Ruoli → Crea Ruolo
2. Inserisci un nome (es. Responsabile Fatture), una descrizione opzionale e scegli un colore per il badge del ruolo
3. Il ruolo viene creato senza permessi. Configurali nella pagina di dettaglio del ruolo.

Tramite API

// Usando il Management Client di Auris
const management = await createManagementClient({ ... })
const role = await management.roles.create({
  name: 'Responsabile Fatture',
  description: 'Può creare e visualizzare le fatture ma non eliminarle',
  color: '#3b82f6',
})

Configurare i Permessi

Categorie di Permessi

L’editor dei permessi nella Console organizza i permessi in 10 categorie:

Impostare i Permessi su un Ruolo

Nella Console, ogni permesso ha un toggle a tre posizioni nella pagina di dettaglio del ruolo:

• ALLOW — Il permesso è concesso agli utenti con questo ruolo
• DENY — Il permesso è esplicitamente negato, sovrascrivendo qualsiasi ALLOW ereditato da altri ruoli
• INHERIT — Il ruolo non concede né nega questo permesso (default)

Un utente ottiene un permesso se almeno uno dei suoi ruoli lo ha impostato su ALLOW e nessuno dei suoi ruoli lo ha impostato su DENY.

Tramite API

Assegnare Ruoli agli Utenti

I ruoli si assegnano agli utenti nella Console (Utenti → [Utente] → scheda Ruoli) o tramite API:

Gli utenti possono avere più ruoli. I permessi di tutti i ruoli vengono uniti. Se un ruolo ha DENY per un permesso, questo sovrascrive il ALLOW di altri ruoli.

Sovrascritture dei Permessi a Livello Utente

I singoli utenti possono avere permessi impostati direttamente, indipendentemente dai loro ruoli. Le sovrascritture utente hanno precedenza su tutti i permessi dei ruoli:

• Un ALLOW a livello utente concede il permesso anche se nessun ruolo lo concede
• Un DENY a livello utente blocca il permesso anche se un ruolo concede ALLOW

Console: Utenti → [Utente] → scheda Permessi → Aggiungi Sovrascrittura

Verificare i Permessi

Lato Server (Route API)

Usa il helper requirePermission() per applicare i permessi nelle route 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 }) => {
  // Raggiunto solo se l'utente ha il permesso view:invoices
  const invoices = await getInvoices(session.user.id)
  return Response.json(invoices)
})
 
export const POST = requirePermission('create:invoices', config, async (req, { session }) => {
  const body = await req.json()
  const invoice = await createInvoice(body, session.user.id)
  return Response.json(invoice, { status: 201 })
})

// Verifica un permesso in un Server Component
import { checkPermission } from '@auris/nextjs/server'
 
export default async function AdminSection() {
  const canManageUsers = await checkPermission('manage:users')
 
  if (!canManageUsers) {
    return <p>Non hai il permesso di gestire gli utenti.</p>
  }
 
  return <UserManagementPanel />
}

Lato Client (Componenti React)

import { useCheckPermission, usePermissions } from '@auris/react'
 
// Verifica un singolo permesso
function InvoiceActions() {
  const { allowed: canCreate, isLoading } = useCheckPermission('create:invoices')
  const { allowed: canDelete } = useCheckPermission('delete:invoices')
 
  if (isLoading) return null
 
  return (
    <div>
      {canCreate && <button>Nuova Fattura</button>}
      {canDelete && <button>Elimina Selezionate</button>}
    </div>
  )
}
 
// Verifica più permessi contemporaneamente
function DashboardNav() {
  const { has, hasAll, hasAny } = usePermissions([
    'view:invoices',
    'view:quotes',
    'manage:users',
    'view:billing',
  ])
 
  return (
    <nav>
      {has('view:invoices') && <a href="/invoices">Fatture</a>}
      {has('view:quotes') && <a href="/quotes">Preventivi</a>}
      {has('manage:users') && <a href="/users">Utenti</a>}
      {has('view:billing') && <a href="/billing">Fatturazione</a>}
      {hasAll(['view:invoices', 'view:quotes']) && <a href="/documents">Tutti i Documenti</a>}
      {hasAny(['manage:users', 'manage:roles']) && <a href="/it/admin">Admin</a>}
    </nav>
  )
}

import { PermissionGate } from '@auris/react'
 
// Renderizza condizionalmente l'UI in base al permesso
function InvoicePage() {
  return (
    <div>
      <h1>Fatture</h1>
 
      {/* Viene renderizzato solo se l'utente ha create:invoices */}
      <PermissionGate permission="create:invoices">
        <button>Nuova Fattura</button>
      </PermissionGate>
 
      {/* Renderizza un fallback per gli utenti non autorizzati */}
      <PermissionGate
        permission="delete:invoices"
        fallback={<span>Accesso in sola lettura</span>}
      >
        <button>Elimina Selezionate</button>
      </PermissionGate>
    </div>
  )
}

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.tuodominio.com', clientId: 'il-tuo-client-id' })
 
// Verifica un singolo permesso
const result = await auris.permissions.checkOne('manage:users')
console.log(result.allowed) // boolean
 
// Verifica più permessi contemporaneamente
const results = await auris.permissions.check([
  'view:invoices',
  'create:invoices',
  'delete:invoices',
])
 
results.forEach((result) => {
  console.log(`${result.permission}: ${result.allowed}`)
})
 
// Ottieni tutti i permessi dell'utente corrente
const allPermissions = await auris.permissions.listUserPermissions()
console.log(allPermissions) // string[] — es. ['view:invoices', 'create:quotes', ...]

API dei Permessi

Ordine di Risoluzione dei Permessi

Quando Auris risolve se un utente ha un permesso specifico, segue questo ordine di precedenza:

1. DENY a livello utente — Se presente, il permesso è negato. Nessuna ulteriore valutazione.
2. ALLOW a livello utente — Se presente (e nessun DENY), il permesso è concesso.
3. Permessi dei ruoli — Se almeno un ruolo ha ALLOW e nessun ruolo ha DENY, il permesso è concesso.
4. Negazione implicita — Se nessuna regola concede il permesso, è negato.

DENY sovrascrittura utente  →  NEGATO (si ferma qui)
ALLOW sovrascrittura utente →  CONCESSO (si ferma qui)
DENY di qualsiasi ruolo     →  NEGATO (si ferma qui)
ALLOW di qualsiasi ruolo    →  CONCESSO
Nessuna corrispondenza      →  NEGATO

Permessi con Scope per Applicazione

I permessi possono facoltativamente avere scope per un’applicazione specifica. Quando un applicationId è incluso nella verifica di un permesso, Auris valuta i permessi nel contesto di quell’applicazione — utile per tenant multi-applicazione dove i ruoli possono differire per applicazione.

const result = 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-per-app-fatturazione',
  }),
})

Guide Correlate

• Autorizzazione Granulare (FGA) — Controllo degli accessi a livello di oggetto oltre ai ruoli
• Claim JWT Personalizzati — Incorpora dati di ruoli e permessi negli access token
• Client Credentials M2M — Autorizzazione per chiamate server-to-server