DOCSEARCHbyAlgolia
Submit Docs

OpenFGA Documentation

website·Indexed 35 days ago

https://openfga.dev/

A fine-grained authorization system based on ReBAC (Relationship-Based Access Control) and Zanzibar concepts. The documentation covers authorization modeling, the OpenFGA Configuration Language, Attribute-Based Access Control (ABAC) patterns, and core concepts such as stores, relationship tuples, and CEL-based conditions.

Tokens
207.8K
Snippets
1.2K
Records
1.4K
Agent score
73%

What's inside OpenFGA

  1. Overview of OpenFGA

    OpenFGA is a scalable open-source authorization system (owned by the CNCF) that implements Relationship-Based Access Control (ReBAC). It allows developers to move authorization logic out of application code into a centralized system, enabling the implementation of Role-Based Access Control (RBAC) and certain Attribute-Based Access Control (ABAC) scenarios. This centralization simplifies auditing, security compliance, and the evolution of authorization policies.

  2. Overview of OpenFGA Configuration Language

    OpenFGA uses a Configuration Language to build authorization models that define object types and the relations between them. This model informs the OpenFGA API on how authorization decisions are made. The language is available in two formats:

    1. JSON: The native format accepted by the OpenFGA API and SDKs, closely following the Zanzibar paper.
    2. DSL: A human-readable syntactic sugar that compiles down to JSON. The DSL is used in the OpenFGA Playground, CLI, and IDE extensions (VS Code and IntelliJ).

  3. Understand Fine-Grained Authorization (FGA)

    Fine-Grained Authorization (FGA) allows for access decisions at the level of individual resources and specific actions (e.g., "Alice can edit document-42") rather than broad roles (e.g., "Alice is an editor"). FGA systems are designed to handle millions of objects and users with rapidly changing permissions, similar to the sharing model used in Google Drive.

  4. Understand Relationship-Based Access Control (ReBAC)

    Relationship-Based Access Control (ReBAC) models permissions as relationships between users and resources rather than static roles or attributes. It treats authorization as a graph problem where access is determined by traversing relationships (e.g., 'Alice is an editor of doc-42' and 'doc-42 is in folder-7').

    ReBAC is ideal when:

    • Permissions involve hierarchy or sharing (e.g., folders, workspaces, organizations).
    • Reverse queries are required (e.g., 'list every document this user can read').
    • Permissions change at write time (e.g., adding a user to a team) rather than being evaluated from request attributes at runtime.

  5. Manage authorization policies with Modular Models

    Modular models allow you to split a single OpenFGA authorization model across multiple files and modules. This is particularly useful for organizations with multiple teams where each team needs to define and evolve their authorization policies independently. By modularizing the model, teams can avoid the complexity of a single monolithic model file and establish clear ownership boundaries, enabling the use of 'code owners' features (such as those in GitHub, GitLab, or Gitea) to manage review processes and ownership.

  6. Understand Fine-Grained Authorization (FGA) concepts

    Fine-grained authorization (FGA) allows access decisions at the level of individual resources and actions (e.g., "Alice can edit document-42") rather than coarse-scope roles (e.g., "Alice is an editor"). FGA is particularly useful for per-resource sharing, hierarchical inheritance (folder $\rightarrow$ document), reverse queries ("List all documents this user can read"), and cross-tenant collaboration.

  7. Understand Types in OpenFGA

    In OpenFGA, a type is a string that defines a class of objects sharing similar characteristics. Types are used to categorize objects within the authorization model. Common examples of types include workspace, repository, organization, and document.

  8. Define authorization requirements for an IoT Security Camera System

    When modeling an IoT Security Camera System in OpenFGA, the following access control requirements must be met:

    • Security Guards: Granted permission to view live and recorded video from Devices.
    • IT Admins: Granted permission to view live and recorded videos and rename Devices.
    • Device Groups: To simplify management, Devices can be organized into groups. Any user (Security Guard or IT Admin) assigned to a Device Group automatically inherits the corresponding permissions for every Device within that group.

  9. Understand the User entity in OpenFGA

    In OpenFGA, a user is an entity that can be related to an object. A user is defined as a combination of a type and an identifier. Users can be represented in several ways: as a specific individual identifier, as a userset (a group of users related to an object via a specific relation), or as a wildcard representing everyone. Users, relations, and objects together form the basis of relationship tuples.
    - Individual user: `user:anne` or `user:4179af14-f0c0-4930-88fd-5570c7bf6f59`
- Userset (group): `organization:org_ajUc9kJ#members` (represents all users related to the organization object as members)
- Everyone: `*`

  10. Understand Direct vs Implied Relationships in OpenFGA

    In OpenFGA, relationships between a user and an object can be either direct or implied:

    • Direct Relationship: A relationship exists because a specific relationship tuple (user=X, relation=R, object=Y) is present in the system and the authorization model allows it based on direct relationship type restrictions.
    • Implied (Computed) Relationship: A relationship exists if the authorization model defines that one relation implies another. For example, if a model defines that any editor is also a viewer, and a user has a direct editor relationship to a document, they have an implied viewer relationship to that same document.

  11. Use Contextual Tuples for session-based authorization

    Contextual Tuples are tuples sent alongside a Check request that are treated as if they exist in the system state for that specific call only. They are not persisted in the store. This is useful for handling user sessions or contexts (e.g., a user acting within a specific organization) without permanently writing tuples to the database.

  12. Implement Relationship-Based Access Control (ReBAC) with OpenFGA

    Relationship-Based Access Control (ReBAC) defines access rules based on relationships between users and objects, or between objects themselves (e.g., "a user can view a document if they have access to its parent folder"). ReBAC is a superset of RBAC and can cover ABAC scenarios when attributes are expressed as relationships. OpenFGA extends ReBAC using Conditions and Contextual Tuples to handle remaining attribute-driven authorization cases.