FGA Debugger

The FGA Debugger is an interactive tool in the Auris Console that allows you to test and troubleshoot your Fine-Grained Authorization (FGA) configuration in real time. It provides three core operations — Check, Expand, and List Objects — each with a visual interface for entering queries and inspecting results.

Access the FGA Debugger at Console → Administration → Fine-Grained Authorization → Debugger.

Prerequisites

Before using the debugger, you need:

1. An active authorization model: At least one FGA model must be created and activated. If no model is active, the debugger page will show an empty state with a link to the Models page.
2. Relationship tuples: The debugger queries your actual tuple store, so you need tuples written for the objects and subjects you want to test.
3. The debug:fga permission: Your admin account must have this permission to access the debugger.

Three Operations

The debugger page is organized into three tabs: Check, Expand, and List Objects. Each tab provides a form for entering the query parameters and a results panel below.

Check

The Check operation answers the question: “Does this subject have this relation to this object?”

This is the most frequently used operation during development and troubleshooting.

Input fields:

How to use it:

Result:

The result panel shows:

• Allowed (green) or Denied (red) — the boolean outcome
• Resolution tree (when Explain is enabled) — the full path the engine followed to reach the decision

Expand

The Expand operation answers the question: “Which subjects have this relation to this object?”

This is useful when you want to see everyone who has access to a specific resource.

Input fields:

Result:

A tree view of all subjects who have the specified relation, grouped by how they obtained it:

• Direct: Subjects with an explicit tuple (for example, document:readme#viewer@user:alice)
• Computed: Subjects who have the relation through a computed userset (for example, all editors are also viewers)
• Inherited: Subjects who inherit the relation from a parent object (for example, via viewer from parent)

List Objects

The List Objects operation answers the question: “Which objects of a given type can this subject access with this relation?”

This is useful when building UIs that show “all documents user Alice can view” or debugging why a user sees (or does not see) certain resources.

Input fields:

Result:

A list of all object IDs of the specified type where the subject has the specified relation. Each result shows the object ID and indicates whether the access is direct, computed, or inherited.

Reading the Visual Resolution Tree

The resolution tree is the most valuable debugging feature. When Explain mode is enabled on a Check operation, the debugger displays a tree visualization showing every step the FGA engine took to reach its decision.

Node Colors

Each node in the tree is color-coded:

Node Types

The tree contains different node types corresponding to the six rewrite types in the FGA model:

Reading a Tree: Example

Consider the following authorization model:

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

A Check for document:readme#viewer@user:alice might produce this tree:

Reading from top to bottom:

1. The engine checks viewer, which is defined as [user] or editor (a union)
2. First branch: direct tuple document:readme#viewer@user:alice — not found (red)
3. Second branch: computed userset editor — evaluates editor on the same object
4. editor is [user] or owner — direct tuple not found, so checks owner
5. owner is [user] or owner from parent — direct tuple document:readme#owner@user:alice found (green)
6. The union short-circuits: owner is true, so editor is true, so viewer is true

The result: Alice can view document:readme because she is the owner (and owners are editors, and editors are viewers).

Common Debugging Scenarios

”Why can’t user X access document Y?”

”Who has editor access to folder Z?”

Use the Expand operation:

1. Set Object Type to folder, Object ID to Z, Relation to editor
2. Click Expand
3. The result shows all direct editors, all users who are editors through computed relations (for example, owners), and all members of groups with editor access

”What documents can user X view?”

Use the List Objects operation:

1. Set Object Type to document, Relation to viewer
2. Set Subject Type to user, Subject ID to X
3. Click List Objects
4. The result lists every document ID where user X has viewer access, whether direct, computed, or inherited

Model Visualization

Below the debugger tabs, the page includes a Model Diagram — an SVG visualization of your active authorization model showing:

• Each type as a node
• Relations as labeled edges between types
• Computed userset arrows (dashed lines)
• tupleToUserset arrows (solid lines with intermediary labels)

The diagram helps you understand the shape of your model at a glance, especially for complex models with deep inheritance chains. Click any type node to highlight its relations and connected types.

Tips for Effective Debugging

Start with Check + Explain mode. The resolution tree tells you exactly what the engine tried and where it succeeded or failed. This is more informative than reading the model definition alone, because it shows the actual tuples in the store.

Work from the bottom up. When a check fails, start at the leaf nodes of the resolution tree. These show the actual tuple lookups. If you see a red this node, that means a specific tuple is missing from the store.

Test both positive and negative cases. After writing tuples, verify that authorized users can access the resource AND that unauthorized users are correctly denied. An overly permissive model is as dangerous as an overly restrictive one.

Use Expand to audit permissions. Periodically run Expand on sensitive resources to verify that only the intended users have access. This is especially important after model changes or bulk tuple operations.

Compare model versions. If authorization behavior changed unexpectedly, check whether the active model was recently updated. Go to Models to see the version history. Only one model is active at a time — activating a new version replaces the previous one.

Related Guides

• FGA / Zanzibar Model — Concepts: how the authorization model and check algorithm work
• Fine-Grained Authorization Guide — Step-by-step guide to implementing FGA
• FGA API Reference — Manage models, tuples, and run checks via the REST API