Depurador FGA

El Depurador FGA es una herramienta interactiva en la Consola Auris que te permite probar y solucionar problemas de tu configuración de Autorización Detallada (FGA) en tiempo real. Proporciona tres operaciones principales — Verificar, Expandir y Listar Objetos — cada una con una interfaz visual para introducir consultas e inspeccionar resultados.

Accede al Depurador FGA en Consola → Administración → Autorización Detallada → Depurador.

Requisitos Previos

Antes de usar el depurador, necesitas:

1. Un modelo de autorización activo: Debe haberse creado y activado al menos un modelo FGA. Si no hay ningún modelo activo, la página del depurador mostrará un estado vacío con un enlace a la página de Modelos.
2. Tuplas de relaciones: El depurador consulta tu almacén de tuplas real, por lo que necesitas tuplas escritas para los objetos y sujetos que deseas probar.
3. El permiso debug:fga: Tu cuenta de administrador debe tener este permiso para acceder al depurador.

Tres Operaciones

La página del depurador está organizada en tres pestañas: Verificar, Expandir y Listar Objetos. Cada pestaña proporciona un formulario para introducir los parámetros de la consulta y un panel de resultados debajo.

Verificar

La operación Verificar responde a la pregunta: “¿Tiene este sujeto esta relación con este objeto?”

Esta es la operación más usada durante el desarrollo y la resolución de problemas.

Campos de entrada:

Cómo usarlo:

Resultado:

El panel de resultados muestra:

• Permitido (verde) o Denegado (rojo) — el resultado booleano
• Árbol de resolución (cuando Explicar está activado) — el camino completo que siguió el motor para llegar a la decisión

Expandir

La operación Expandir responde a la pregunta: “¿Qué sujetos tienen esta relación con este objeto?”

Es útil cuando quieres ver todos los que tienen acceso a un recurso específico.

Campos de entrada:

Resultado:

Una vista de árbol de todos los sujetos que tienen la relación especificada, agrupados por cómo la obtuvieron:

• Directo: Sujetos con una tupla explícita (por ejemplo, document:readme#viewer@user:alice)
• Calculado: Sujetos que tienen la relación mediante un userset calculado (por ejemplo, todos los editores son también viewers)
• Heredado: Sujetos que heredan la relación de un objeto padre (por ejemplo, mediante viewer from parent)

Listar Objetos

La operación Listar Objetos responde a la pregunta: “¿A qué objetos de un tipo dado puede acceder este sujeto con esta relación?”

Es útil para construir interfaces que muestren “todos los documentos que Alice puede ver” o para depurar por qué un usuario ve (o no ve) ciertos recursos.

Campos de entrada:

Resultado:

Una lista de todos los IDs de objeto del tipo especificado donde el sujeto tiene la relación indicada. Cada resultado muestra el ID del objeto e indica si el acceso es directo, calculado o heredado.

Leer el Árbol de Resolución Visual

El árbol de resolución es la función de depuración más valiosa. Cuando el modo Explicar está activado en una operación Verificar, el depurador muestra una visualización en árbol que muestra cada paso que dio el motor FGA para llegar a su decisión.

Colores de los Nodos

Cada nodo del árbol está codificado por color:

Tipos de Nodos

El árbol contiene diferentes tipos de nodos que corresponden a los seis tipos de reescritura en el modelo FGA:

Leer un Árbol: Ejemplo

Considera el siguiente modelo de autorización:

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

Una Verificación de document:readme#viewer@user:alice podría producir este árbol:

Leyendo de arriba a abajo:

1. El motor comprueba viewer, que está definido como [user] or editor (una unión)
2. Primera rama: tupla directa document:readme#viewer@user:alice — no encontrada (rojo)
3. Segunda rama: userset calculado editor — evalúa editor en el mismo objeto
4. editor es [user] or owner — tupla directa no encontrada, por lo que comprueba owner
5. owner es [user] or owner from parent — tupla directa document:readme#owner@user:alice encontrada (verde)
6. La unión hace cortocircuito: owner es verdadero, por lo que editor es verdadero, por lo que viewer es verdadero

El resultado: Alice puede ver document:readme porque es la propietaria (y los propietarios son editores, y los editores son visores).

Escenarios de Depuración Comunes

”¿Por qué el usuario X no puede acceder al documento Y?”

”¿Quién tiene acceso de editor a la carpeta Z?”

Usa la operación Expandir:

1. Establece el Tipo de Objeto en folder, el ID de Objeto en Z, la Relación en editor
2. Haz clic en Expandir
3. El resultado muestra todos los editores directos, todos los usuarios que son editores mediante relaciones calculadas (por ejemplo, propietarios) y todos los miembros de grupos con acceso de editor

”¿Qué documentos puede ver el usuario X?”

Usa la operación Listar Objetos:

1. Establece el Tipo de Objeto en document, la Relación en viewer
2. Establece el Tipo de Sujeto en user, el ID de Sujeto en X
3. Haz clic en Listar Objetos
4. El resultado lista cada ID de documento donde el usuario X tiene acceso de visor, ya sea directo, calculado o heredado

Visualización del Modelo

Debajo de las pestañas del depurador, la página incluye un Diagrama del Modelo — una visualización SVG de tu modelo de autorización activo que muestra:

• Cada tipo como un nodo
• Relaciones como aristas etiquetadas entre tipos
• Flechas de userset calculado (líneas discontinuas)
• Flechas tupleToUserset (líneas sólidas con etiquetas intermedias)

El diagrama te ayuda a entender la forma de tu modelo de un vistazo, especialmente para modelos complejos con cadenas de herencia profundas. Haz clic en cualquier nodo de tipo para resaltar sus relaciones y tipos conectados.

Consejos para una Depuración Eficaz

Empieza con Verificar + modo Explicar. El árbol de resolución te dice exactamente qué probó el motor y dónde tuvo éxito o falló. Esto es más informativo que leer solo la definición del modelo, porque muestra las tuplas reales en el almacén.

Trabaja de abajo hacia arriba. Cuando una verificación falla, empieza por los nodos hoja del árbol de resolución. Estos muestran las búsquedas de tuplas reales. Si ves un nodo this rojo, significa que falta una tupla específica en el almacén.

Prueba casos tanto positivos como negativos. Tras escribir tuplas, verifica que los usuarios autorizados puedan acceder al recurso Y que los usuarios no autorizados sean correctamente denegados. Un modelo demasiado permisivo es tan peligroso como uno demasiado restrictivo.

Usa Expandir para auditar permisos. Ejecuta periódicamente Expandir en recursos sensibles para verificar que solo los usuarios previstos tienen acceso. Esto es especialmente importante después de cambios en el modelo u operaciones masivas de tuplas.

Compara versiones del modelo. Si el comportamiento de autorización cambió de forma inesperada, comprueba si el modelo activo fue actualizado recientemente. Ve a Modelos para ver el historial de versiones. Solo un modelo está activo a la vez — activar una nueva versión reemplaza la anterior.

Guías Relacionadas

• Modelo FGA / Zanzibar — Conceptos: cómo funcionan el modelo de autorización y el algoritmo de verificación
• Guía de Autorización Detallada — Guía paso a paso para implementar FGA
• Referencia de la API FGA — Gestionar modelos, tuplas y ejecutar verificaciones mediante la API REST