====== OpenFGA ======

OpenFGA is an open-source authorization engine. Its only job is to answer one
question: **"Is this user allowed to do this thing?"** It does not run your app.
It sits beside your app and says yes or no.

===== Why it exists =====

Permission logic gets messy. Rules like "only the owner can edit" or "managers
can approve" spread across your code and get tangled.

OpenFGA pulls all of that into one place. Your app stops asking //"does this user
have the right role?"// and instead asks OpenFGA //"can this user do this?"//

  * One source of truth.
  * One place to change the rules.

It is based on a Google paper called **Zanzibar**, the system Google uses for
Docs, Drive, and YouTube. OpenFGA is an open version of that idea.

===== What it is built on: ReBAC =====

OpenFGA uses **relationship-based access control** (ReBAC).

  * **RBAC** (older): a user has a role, a role has permissions. Simple but rigid.
  * **ReBAC**: access comes from how objects connect to each other.

Example of relationships:

  * A user is the **owner** of a document.
  * A document is **inside** a folder.
  * So the user can also reach things in that folder.

Access flows along these links.

===== The main parts =====

^ Part ^ What it is ^
| **[[security:authorization:openfga:store|Store]]** | A container holding your model and data. One project. |
| **[[security:authorization:openfga:authorization-model|Authorization model]]** | The rules. Written in a DSL. Holds the //shape//, not real users. |
| **[[security:authorization:openfga:relationship-tuples|Relationship tuples]]** | The data. Small facts as ''(user, relation, object)''. |
| **[[security:authorization:openfga:check-API|Check API]]** | The question. Returns ''allowed: true'' or ''allowed: false''. |

A tuple looks like this:

<code>
(account:123, assignee, role:manager)
</code>

This means "account 123 is an assignee of role manager". These tuples often come
from your database through CDC (Change Data Capture).

===== How a Check works =====

The model plus the tuples form a graph. A Check walks that graph.

Example question:

<code>
Check: can account:123 do pos_order_approve on organization:default?
</code>

The steps:

  - Your app asks the question.
  - OpenFGA reads the model to learn what path would allow this.
  - OpenFGA walks the tuples:
    * account:123 is assignee of role:manager
    * role:manager grants pos_order_approve
  - Both links connect, so the answer is ''allowed: true''.

If any link is missing (for example, 123 was never made a manager), the walk
fails and the answer is ''allowed: false''.

===== Other useful features =====

  * **List objects**: "Which documents can this user read?" Good for filtering results.
  * **List users**: "Who can access this document?" Good for sharing screens.
  * **Conditions (ABAC)**: grants that only apply if some data is true, like
    "only under $500" or "only during work hours".

===== How it fits your app =====

Input → Process → Output:

  * **Input**: write the model once, keep tuples in sync with your database.
  * **Process**: on every sensitive action, call Check before doing the work.
  * **Output**: OpenFGA returns ''true'' or ''false''; your app allows or blocks it.

The result: rules live in one clear place, checks are fast, and different teams
can own different parts of the model.

===== See also =====

  * [[https://openfga.dev|OpenFGA official site]]
  * [[https://research.google/pubs/pub48190/|Google Zanzibar paper]]