Autorizzazione Granulare (FGA)

Auris FGA è un motore di autorizzazione basata sulle relazioni (ReBAC) in stile Zanzibar per il controllo degli accessi a livello di oggetto. Mentre RBAC risponde a “questo utente ha il permesso view:invoices a livello globale?”, FGA risponde a “questo utente ha la relazione viewer sul documento #123 specificamente?”.

FGA è lo strumento giusto quando l’autorizzazione dipende dalle relazioni tra oggetti specifici — non solo dai ruoli utente.

Casi d’uso comuni:

• Un sistema di condivisione documenti dove ogni documento ha proprietari, editor e visualizzatori individuali
• Un SaaS multi-tenant dove l’accesso a un progetto dipende dall’appartenenza all’organizzazione
• Un file system dove i permessi di una cartella vengono ereditati dal suo contenuto
• Un portale B2B dove i contatti clienti possono vedere solo i dati della propria organizzazione

Concetti Fondamentali

Oggetti

Un oggetto è un’entità nel tuo sistema identificata da un tipo e un ID, scritta come tipo:id. Esempi:

• document:inv-2024-001
• folder:fatture-q4
• project:redesign-sito
• organization:acme-corp

Relazioni

Una relazione descrive come un soggetto è connesso a un oggetto. Le relazioni sono definite nel modello di autorizzazione. Esempi: owner, editor, viewer, member, admin.

Soggetti

Un soggetto è l’entità che viene autorizzata. I soggetti sono scritti anch’essi come tipo:id. Il tipo di soggetto più comune è user. I soggetti possono anche essere insiemi — organization:acme-corp#member significa “chiunque sia membro dell’organizzazione acme-corp”.

Tuple

Una tuple di relazione è un fatto memorizzato: (tipoOggetto, idOggetto, relazione, tipoSoggetto, idSoggetto). Ad esempio: “l’utente alice è un viewer del documento report-2024” viene memorizzato come:

{
  "objectType": "document",
  "objectId": "report-2024",
  "relation": "viewer",
  "subjectType": "user",
  "subjectId": "alice"
}

Modelli di Autorizzazione

Il modello di autorizzazione è uno schema scritto in un DSL compatibile con OpenFGA. Definisce quali tipi esistono e quali relazioni ogni tipo supporta.

Sintassi DSL

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type project
  relations
    define org: [organization]
    define admin: [user] or admin from org
    define editor: [user] or admin
    define viewer: [user] or editor

type document
  relations
    define project: [project]
    define owner: [user]
    define editor: [user] or owner or editor from project
    define viewer: [user] or editor or viewer from project or member from org of project

Questo modello definisce:

• Qualsiasi utente può essere member o admin di un’organizzazione
• Un progetto appartiene a un’organizzazione; gli admin del progetto ereditano dagli admin dell’organizzazione
• Un documento appartiene a un progetto; il set dei suoi viewer include viewer diretti, editor, viewer del progetto e membri dell’organizzazione

Tipi di Riscrittura

Auris FGA supporta 6 tipi di riscrittura per calcolare l’appartenenza alle relazioni:

Creare e Attivare un Modello

Scrivere Tuple

Le tuple sono i dati di runtime — le relazioni effettive tra oggetti e soggetti nella tua applicazione.

// Condividi un documento con un utente (scrivi una tupla)
await fetch('/api/fga/tuples', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    writes: [
      {
        objectType: 'document',
        objectId: 'report-2024',
        relation: 'viewer',
        subjectType: 'user',
        subjectId: 'bob',
      },
    ],
  }),
})
 
// Revoca l'accesso (elimina una tupla)
await fetch('/api/fga/tuples', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    deletes: [
      {
        objectType: 'document',
        objectId: 'report-2024',
        relation: 'viewer',
        subjectType: 'user',
        subjectId: 'bob',
      },
    ],
  }),
})

Verificare l’Autorizzazione

Check

L’endpoint check risponde a “il soggetto X ha la relazione R sull’oggetto Y?”

Expand

L’endpoint expand restituisce l’insieme completo dei soggetti che hanno una determinata relazione su un oggetto — utile per il debug e per costruire pannelli di condivisione visibili agli utenti.

List Objects

L’endpoint list-objects restituisce tutti gli oggetti di un determinato tipo su cui un soggetto ha una relazione specificata — utile per filtrare i risultati delle query.

Utilizzo con l’SDK

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.tuodominio.com', clientId: 'il-tuo-client-id' })
 
// Verifica una singola relazione
const { allowed } = await auris.fga.check({
  object: 'document:report-2024',
  relation: 'viewer',
  subject: 'user:bob',
})
console.log(allowed) // true | false
 
// Elenca tutti i documenti che l'utente corrente può visualizzare
const { objects } = await auris.fga.listObjects({
  objectType: 'document',
  relation: 'viewer',
  subject: 'user:current',
})
console.log(objects) // ['document:report-2024', 'document:fattura-001', ...]
 
// Scrivi tuple programmaticamente
await auris.fga.writeTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'editor',
    subjectType: 'user',
    subjectId: 'alice',
  },
])
 
// Elimina tuple
await auris.fga.deleteTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'viewer',
    subjectType: 'user',
    subjectId: 'bob',
  },
])

import { useFga } from '@auris/react'
 
function DocumentPage({ documentId }) {
  const { check, listObjects, isLoading } = useFga()
  const [canEdit, setCanEdit] = useState(false)
 
  useEffect(() => {
    check({
      object: `document:${documentId}`,
      relation: 'editor',
    }).then((result) => setCanEdit(result.allowed))
  }, [documentId])
 
  return (
    <div>
      <h1>Documento</h1>
      {canEdit ? (
        <button>Modifica Documento</button>
      ) : (
        <span>Sola lettura</span>
      )}
    </div>
  )
}
 
// Pannello di condivisione — mostra chi ha accesso
function SharingPanel({ documentId }) {
  const { expand } = useFga()
  const [viewers, setViewers] = useState([])
 
  useEffect(() => {
    expand({
      objectType: 'document',
      objectId: documentId,
      relation: 'viewer',
    }).then((result) => setViewers(result.subjects))
  }, [documentId])
 
  return (
    <ul>
      {viewers.map((viewer) => (
        <li key={viewer.subjectId}>{viewer.subjectId}</li>
      ))}
    </ul>
  )
}

// FGA check lato server in un Route Handler o Server Component
import { createServerFgaClient } from '@auris/nextjs/server'
import { getSession } from '@auris/nextjs/server'
 
export async function GET(req: Request, { params }: { params: { id: string } }) {
  const session = await getSession()
  if (!session) return Response.json({ error: 'Non autorizzato' }, { status: 401 })
 
  const fga = await createServerFgaClient()
 
  const { allowed } = await fga.check({
    object: `document:${params.id}`,
    relation: 'viewer',
    subject: `user:${session.user.id}`,
  })
 
  if (!allowed) {
    return Response.json({ error: 'Accesso negato' }, { status: 403 })
  }
 
  const document = await getDocument(params.id)
  return Response.json(document)
}
 
// Filtra una lista ai soli oggetti che l'utente può vedere
export default async function DocumentsPage() {
  const session = await getSession()
  const fga = await createServerFgaClient()
 
  const { objects } = await fga.listObjects({
    objectType: 'document',
    relation: 'viewer',
    subject: `user:${session.user.id}`,
  })
 
  const documentIds = objects.map((o) => o.split(':')[1])
  const documents = await getDocumentsByIds(documentIds)
 
  return <DocumentList documents={documents} />
}

Pattern Comuni

Modello Google Drive

Una gerarchia dove i permessi delle cartelle si propagano ai documenti:

type user

type folder
  relations
    define owner: [user]
    define editor: [user] or owner
    define viewer: [user] or editor
    define parent: [folder]
    define editor_via_parent: editor from parent
    define viewer_via_parent: viewer from parent

type document
  relations
    define owner: [user]
    define parent_folder: [folder]
    define editor: [user] or owner or editor_via_parent from parent_folder
    define viewer: [user] or editor or viewer_via_parent from parent_folder

Modello SaaS Multi-Tenant

L’appartenenza all’organizzazione controlla l’accesso a progetti e risorse:

type user

type organization
  relations
    define admin: [user]
    define member: [user] or admin

type project
  relations
    define organization: [organization]
    define admin: [user] or admin from organization
    define member: [user] or member from organization or admin

type resource
  relations
    define project: [project]
    define owner: [user]
    define editor: [user] or owner or admin from project
    define viewer: [user] or editor or member from project

Debug con la Console FGA

La Console Auris include un FGA Debugger in Console → Autorizzazione → Debugger con tre strumenti:

• Check: Testa qualsiasi combinazione oggetto/relazione/soggetto e vedi l’albero di risoluzione
• Expand: Visualizza l’insieme completo dei soggetti per qualsiasi relazione
• List Objects: Trova tutti gli oggetti a cui un utente ha accesso

L’albero di risoluzione mostra esattamente quali tuple e riscritture del modello hanno portato al risultato allowed: true o allowed: false — indispensabile per diagnosticare risultati di autorizzazione inattesi.

Template di Modello

La Console fornisce tre template di modello per iniziare rapidamente:

• Basic: Modello semplice utente/risorsa con owner, editor, viewer
• SaaS: Gerarchia organizzazione → progetto → risorsa con appartenenza ai team
• Drive: Gerarchia cartella/documento annidata con permessi ereditati

Guide Correlate

• Ruoli e Permessi (RBAC) — Autorizzazione basata sui ruoli per permessi a livello applicazione
• Claim JWT Personalizzati — Incorpora dati derivati da FGA negli access token
• Client Credentials M2M — Verifiche FGA lato server da servizi backend