Authorization

OpenFGA Relationship-Based Access Control (ReBAC) with relationship tuples, computed permissions, hierarchical inheritance, and the require_permission pattern.

Authorization

CRAFT uses OpenFGA for authorization, implementing Relationship-Based Access Control (ReBAC). Unlike traditional RBAC where roles grant flat permission sets, ReBAC models permissions as relationships between users and resources, enabling fine-grained, hierarchical access control.

OpenFGA is the open-source implementation of Google’s Zanzibar authorization system. It evaluates permission checks in single-digit milliseconds, making it suitable for per-request authorization in API endpoints.

Core Concepts

Relationship Tuples

A relationship tuple is the fundamental building block. It states: “This user/group has this relation on this resource.”

user:jane          owner      organization:acme-corp
group:org-admins   admin      organization:acme-corp
user:bob           developer  project:analytics-prod

Tuples are stored in OpenFGA and queried during permission checks.

Resource Types

The authorization model defines types for every resource in the platform:

Type	Service	Description
organization	Governance	Top-level tenant boundary
project	Governance	Resource grouping within an organization
artifact	Assets	Generated outputs (reports, visualizations)
file	Assets	Uploaded files and documents
data_connection	Assets	External data source connections
mcp_server	Assets	Model Context Protocol servers
api_server	Assets	API server registrations
model	Assets	ML model registrations

Relations (Roles)

Relations represent the roles a user or group can have on a resource:

Relation	Scope	Description
owner	All types	Full control including deletion
admin	Organization, Project	Administrative access, user/project management
member	Organization	Standard membership with read access
developer	Project, Resources	Create and manage resources
operator	Project, Resources	Execute and operate resources
viewer	Project, Resources	Read-only access

Computed Permissions

Computed permissions are derived from relations using OR logic. For example, can_read is granted to anyone with viewer, operator, developer, admin, or owner relation:

define can_read: viewer or operator or developer or admin or owner

The full set of computed permissions:

Permission	Description
can_read	View the resource
can_write	Modify the resource
can_delete	Remove the resource
can_execute	Run/invoke the resource (agents, MCP servers, data connections)
can_create_resources	Create child resources (project-level)
can_share	Share with other users
can_read_secrets	View associated secrets
can_manage_secrets	Create/update/delete secrets
can_read_metadata	View resource metadata
can_manage_metadata	Modify resource metadata
can_manage_projects	Create/delete projects (organization-level)
can_manage_users	Manage user memberships (organization-level)

Permission Inheritance

The authorization model uses OpenFGA’s from keyword to implement hierarchical permission inheritance:

Projects inherit from Organizations
Resources inherit from Projects
Resource permissions can compute from Project permissions (e.g., can_delete from project)

This means an organization admin automatically has appropriate access to all projects and resources within their organization, without needing explicit tuples on each resource:

# This single tuple:
group:org-admins   admin   organization:acme-corp

# Grants (via inheritance):
# - can_read on all projects in acme-corp
# - can_write on all projects in acme-corp
# - can_delete on all projects in acme-corp
# - can_read on all resources in those projects
# - can_write on all resources in those projects
# - ... and so on

The inheritance chain is established via parent link tuples:

project:analytics#organization@organization:acme-corp
data_connection:pg-prod#project@project:analytics

Computed delegation: can_delete from project

For resource types like data_connection, the schema computes resource-level permissions from project-level permissions. For example, can_delete on a data connection is satisfied if the user has delete rights on the parent project:

type data_connection
  relations
    define project: [project]
    define can_delete: owner or admin or can_delete from project
    define can_execute: operator or developer or admin or owner
                        or can_execute from project

This means an organization owner who has can_delete on every project (via the org-from-project chain above) can also delete every project-scoped resource without per-resource tuples.

Service worker permissions on data_connection

Service workers (background tasks like the data-readiness worker, scheduled enrichment runs, and dataset sync jobs) need to invoke data connections. The schema grants can_execute on data_connection to the service-worker role at the project level so workers can POST /assets/data/{resource_uri}/verify and GET /assets/data/{resource_uri}/secret against any connection in their assigned project, without needing a per-connection tuple.

This follows the same pattern as can_create_resources on project for service workers: a single role binding at the parent grants narrow operational permissions across all child resources.

Authorization Schema (OpenFGA DSL)

The schema is defined in openfga-schema.fga and compiled to openfga-schema.json for runtime use. Here is a simplified excerpt showing the project type:

type project
  relations
    define organization: [organization]

    # Direct assignments
    define owner: [user, group#member, role#assignee]
    define admin: [user, group#member, role#assignee]
    define developer: [user, group#member, role#assignee]
    define operator: [user, group#member, role#assignee]
    define viewer: [user, group#member, role#assignee]

    # Computed permissions with inheritance
    define can_read: viewer or operator or developer or admin or owner
                     or admin from organization or owner from organization
    define can_write: operator or developer or admin or owner
                      or admin from organization or owner from organization
    define can_delete: owner or admin
                       or owner from organization or admin from organization
    define can_create_resources: developer or admin or owner
                                or admin from organization or owner from organization

When modifying the OpenFGA schema, always update both the .fga DSL file and regenerate the .json runtime file by running ./scripts/generate-openfga-schema.sh. The Governance service reads only the JSON file at startup. Adding new permissions is safe; renaming or removing is a breaking change.

The require_permission Pattern

All API endpoints use the require_permission() dependency to enforce authorization. This is implemented in the shared common package and used consistently across all services:

from common.permissions import Permissions, require_permission

@router.delete("/data/{resource_uri}")
async def delete_data_connection(
    resource_uri: str,
    _: None = Depends(require_permission(
        Permissions.DATA_CONNECTION,                       # Resource type
        Permissions.DATA_CONNECTION.actions.CAN_DELETE,     # Required permission
        "resource_uri"                                      # Path parameter with resource ID
    ))
):
    ...

Permission Check Flow

When require_permission() is invoked, the following occurs:

1. Extract Resource ID

   The resource ID is resolved from path parameters, query parameters, or headers based on the configuration.

2. Get Auth Context

   The Auth object is extracted from the validated JWT, providing sub (user ID) and teams (group memberships).

3. Check OpenFGA

   The permission checker queries OpenFGA with:

   • User: user:{sub} and each group:{group_name}#member
   • Relation: The computed permission (e.g., can_delete)
   • Object: {resource_type}:{resource_id}

   If any user or group check returns true, access is granted.

4. Return Result

   • 200/success: Permission granted, the endpoint handler executes
   • 403 Forbidden: Permission denied, the request is rejected
   • 500 Internal Server Error: Permission system misconfigured

Permission API

The Governance service exposes a Permissions API for programmatic permission management:

Endpoint	Method	Description
/governance/permissions/check	GET	Check if a user has a specific permission on a resource
/governance/permissions/grant	POST	Grant a relation to a user or group on a resource
/governance/permissions/revoke	POST	Revoke a relation from a user or group
/governance/permissions/set-parent	POST	Establish a parent-child relationship for inheritance
/governance/permissions/delete-all	POST	Remove all permission tuples for a resource (cleanup)

Assets and Utils never call the Permissions API directly. They use the require_permission() dependency, which internally forwards the user’s JWT to the Governance service for permission validation via the auto-generated SDK.

Keycloak Groups and OpenFGA

The bridge between Keycloak (identity) and OpenFGA (authorization) is Keycloak groups:

1. Users are assigned to groups in Keycloak (e.g., org-admins, project-developers)
2. A groups mapper on the realm ensures group memberships appear in the JWT groups claim
3. During bootstrap, permission tuples map groups to OpenFGA relations (e.g., group:org-admins#member -> admin on organization)
4. At runtime, require_permission() checks both the user’s direct tuples and their group-based tuples

This means adding a user to a Keycloak group is sufficient to grant them the corresponding platform permissions — no separate OpenFGA management is needed.

Next Steps

Authentication

Understand how JWT tokens carry group claims for authorization.

Organizations

See how organization-level permissions are bootstrapped.

Projects

Learn about project-level role assignments and inheritance.

Multi-Tenancy

Explore the full tenant isolation architecture.