Autorización de Grano Fino (FGA)

Auris FGA es un motor de autorización basada en relaciones (ReBAC) al estilo Zanzibar para el control de acceso a nivel de objeto. Mientras que RBAC responde “¿tiene este usuario el permiso global view:invoices?”, FGA responde “¿tiene este usuario la relación viewer sobre el documento #123 específicamente?”.

FGA es la herramienta adecuada cuando la autorización depende de relaciones entre objetos específicos — no solo de los roles del usuario.

Casos de uso comunes:

• Un sistema de compartición de documentos donde cada documento tiene sus propios propietarios, editores y lectores
• Un SaaS multi-tenant donde el acceso a un proyecto depende de la pertenencia a una organización
• Un sistema de archivos donde los permisos de una carpeta son heredados por su contenido
• Un portal B2B donde los contactos de cada cliente solo pueden ver los datos de su propia organización

Conceptos Fundamentales

Objetos

Un objeto es una entidad en tu sistema identificada por un tipo y un ID, escrito como tipo:id. Ejemplos:

• document:inv-2024-001
• folder:invoices-q4
• project:website-redesign
• organization:acme-corp

Relaciones

Una relación describe cómo un sujeto está conectado a un objeto. Las relaciones se definen en el modelo de autorización. Ejemplos: owner, editor, viewer, member, admin.

Sujetos

Un sujeto es la entidad que se autoriza. Los sujetos también se escriben como tipo:id. El tipo de sujeto más común es user. Los sujetos también pueden ser conjuntos — organization:acme-corp#member significa “cualquier persona que sea miembro de la organización acme-corp”.

Tuplas

Una tupla de relación es un hecho almacenado: (objectType, objectId, relation, subjectType, subjectId). Por ejemplo: “user:alice es viewer del document:report-2024” se almacena como:

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

Modelos de Autorización

El modelo de autorización es un esquema escrito en un DSL compatible con OpenFGA. Define qué tipos existen y qué relaciones soporta cada tipo.

Sintaxis 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

Este modelo define:

• Cualquier usuario puede ser member o admin de una organización
• Un proyecto pertenece a una organización; los administradores del proyecto heredan de los de la organización
• Un documento pertenece a un proyecto; su conjunto de viewers incluye viewers directos, editores, viewers del proyecto y miembros de la organización

Tipos de Reescritura

Auris FGA soporta 6 tipos de reescritura para calcular la pertenencia a una relación:

Crear y Activar un Modelo

Escritura de Tuplas

Las tuplas son los datos de tiempo de ejecución — las relaciones reales entre objetos y sujetos en tu aplicación.

// Compartir un documento con un usuario (escribir 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',
      },
    ],
  }),
})
 
// Revocar acceso (eliminar 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',
      },
    ],
  }),
})

Verificación de Autorización

Check

El endpoint check responde “¿tiene el sujeto X la relación R sobre el objeto Y?”

Expand

El endpoint expand devuelve el conjunto completo de sujetos que tienen una relación dada sobre un objeto, útil para depuración y para construir paneles de compartición orientados al usuario.

List Objects

El endpoint list-objects devuelve todos los objetos de un tipo dado sobre los que un sujeto tiene una relación especificada — útil para filtrar resultados de consultas.

Uso del SDK

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({ domain: 'auth.tudominio.com', clientId: 'tu-client-id' })
 
// Verificar una sola relación
const { allowed } = await auris.fga.check({
  object: 'document:report-2024',
  relation: 'viewer',
  subject: 'user:bob',
})
console.log(allowed) // true | false
 
// Listar todos los documentos que el usuario actual puede ver
const { objects } = await auris.fga.listObjects({
  objectType: 'document',
  relation: 'viewer',
  subject: 'user:current',
})
console.log(objects) // ['document:report-2024', 'document:invoice-001', ...]
 
// Escribir tuplas programáticamente
await auris.fga.writeTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'editor',
    subjectType: 'user',
    subjectId: 'alice',
  },
])
 
// Eliminar tuplas
await auris.fga.deleteTuples([
  {
    objectType: 'document',
    objectId: 'report-2024',
    relation: 'viewer',
    subjectType: 'user',
    subjectId: 'bob',
  },
])

import { useFga } from '@auris/react'
 
function PaginaDocumento({ documentId }) {
  const { check, listObjects, isLoading } = useFga()
  const [puedeEditar, setPuedeEditar] = useState(false)
 
  useEffect(() => {
    check({
      object: `document:${documentId}`,
      relation: 'editor',
    }).then((result) => setPuedeEditar(result.allowed))
  }, [documentId])
 
  return (
    <div>
      <h1>Documento</h1>
      {puedeEditar ? (
        <button>Editar Documento</button>
      ) : (
        <span>Solo lectura</span>
      )}
    </div>
  )
}
 
// Panel de compartición — mostrar quién tiene acceso
function PanelComparticion({ documentId }) {
  const { expand } = useFga()
  const [lectores, setLectores] = useState([])
 
  useEffect(() => {
    expand({
      objectType: 'document',
      objectId: documentId,
      relation: 'viewer',
    }).then((result) => setLectores(result.subjects))
  }, [documentId])
 
  return (
    <ul>
      {lectores.map((lector) => (
        <li key={lector.subjectId}>{lector.subjectId}</li>
      ))}
    </ul>
  )
}

// Verificación FGA del lado del servidor en 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: 'No autorizado' }, { 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: 'Prohibido' }, { status: 403 })
  }
 
  const documento = await getDocument(params.id)
  return Response.json(documento)
}
 
// Filtrar una lista para mostrar solo los objetos que el usuario puede ver
export default async function PaginaDocumentos() {
  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 documentos = await getDocumentsByIds(documentIds)
 
  return <ListaDocumentos documentos={documentos} />
}

Patrones Comunes

Modelo Google Drive

Una jerarquía donde los permisos de las carpetas se propagan a los documentos:

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

Modelo SaaS Multi-Tenant

La pertenencia a una organización controla el acceso a proyectos y recursos:

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

Depuración con la Consola FGA

La Consola de Auris incluye un Depurador de FGA en Consola → Autorización → Depurador con tres herramientas:

• Check: Prueba cualquier combinación objeto/relación/sujeto y visualiza el árbol de resolución
• Expand: Visualiza el conjunto completo de sujetos para cualquier relación
• List Objects: Encuentra todos los objetos a los que un usuario tiene acceso

El árbol de resolución muestra exactamente qué tuplas y reescrituras del modelo llevaron al resultado allowed: true o allowed: false — esencial para diagnosticar resultados de autorización inesperados.

Plantillas de Modelo

La Consola proporciona tres plantillas de modelo para empezar rápidamente:

• Básico: Modelo usuario/recurso simple con owner, editor, viewer
• SaaS: Jerarquía organización → proyecto → recurso con pertenencia a equipo
• Drive: Jerarquía anidada carpeta/documento con permisos heredados

Guías Relacionadas

• Roles y Permisos (RBAC) — Autorización basada en roles para permisos a nivel de aplicación
• Claims JWT Personalizados — Incrustar datos derivados de FGA en los access tokens
• Credenciales M2M (Client Credentials) — Verificaciones FGA del lado del servidor desde servicios backend