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
    ))
):
    ...

from common.permissions import Permissions, require_permission, HEADER_PROJECT_ID

@router.post("/data")
async def create_data_connection(
    payload: DataConnectionCreateRequest,
    _: None = Depends(require_permission(
        Permissions.PROJECT,                               # Check on the project
        Permissions.PROJECT.actions.CAN_CREATE_RESOURCES,   # Required permission
        HEADER_PROJECT_ID                                   # From X-Project-ID header
    ))
):
    ...

from common.permissions import require_permission_dynamic

@router.get("/{resource_type}/{resource_id}/secrets")
async def list_secrets(
    resource_type: str,
    resource_id: str,
    _: None = Depends(require_permission_dynamic(
        resource_type_param="resource_type",   # Resolved from path parameter
        permission="can_read_secrets",
        resource_id_param="resource_id"
    ))
):
    ...

Permission Check Flow

When require_permission() is invoked, the following occurs:

Extract Resource ID

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

Get Auth Context

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

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.

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:

Users are assigned to groups in Keycloak (e.g., org-admins, project-developers)
A groups mapper on the realm ensures group memberships appear in the JWT groups claim
During bootstrap, permission tuples map groups to OpenFGA relations (e.g., group:org-admins#member -> admin on organization)
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.

Overview

Identity & Access

Agents & Services

Memory

Data & Gateways

Authorization

Authorization

Core Concepts

Permission Inheritance

Computed delegation: `can_delete from project`

Service worker permissions on `data_connection`

Authorization Schema (OpenFGA DSL)

The require_permission Pattern

Permission Check Flow

Permission API

Keycloak Groups and OpenFGA

Next Steps

Authentication

Organizations

Projects

Multi-Tenancy

​Authorization

​Core Concepts

​Permission Inheritance

​Computed delegation: can_delete from project

​Service worker permissions on data_connection

​Authorization Schema (OpenFGA DSL)

​The require_permission Pattern

​Permission Check Flow

​Permission API

​Keycloak Groups and OpenFGA

​Next Steps

Authentication

Organizations

Projects

Multi-Tenancy

Authorization

Core Concepts

Permission Inheritance

Computed delegation: `can_delete from project`

Service worker permissions on `data_connection`

Authorization Schema (OpenFGA DSL)

The require_permission Pattern

Permission Check Flow

Permission API

Keycloak Groups and OpenFGA

Next Steps