Current OpenFGA Backend

Summary

Keymate uses OpenFGA as its fine-grained authorization backend. OpenFGA is an open-source implementation of the Zanzibar authorization model, providing relationship-based access control through a tuple-based storage system and graph evaluation engine. The FGA Engine communicates with OpenFGA to store relationships and evaluate authorization queries.

Why It Exists

OpenFGA provides a production-ready implementation of the Zanzibar model with:

• High-performance relationship queries optimized for authorization workloads
• Flexible authorization model DSL for defining entity types and relations
• Built-in support for relationship inheritance and computed relations
• HTTP and gRPC APIs for integration flexibility

Keymate leverages OpenFGA to deliver enterprise-grade fine-grained authorization without building a custom graph authorization engine.

Where It Fits in Keymate

OpenFGA runs as a dedicated service that the FGA Engine connects to for all relationship operations. The integration uses OpenFGA's standard APIs.

Boundaries

What it covers:

• OpenFGA store and authorization model management
• Relationship tuple operations (check, write, read, list)
• Authorization model versioning
• OpenFGA API integration

What it does not cover:

• Custom backend implementations
• Data migration between backends
• OpenFGA cluster management (see Deployment Model)

How It Works

Store and Model

OpenFGA organizes data into stores, each containing:

Component	Description
Store	Isolated container for authorization data
Authorization Model	Schema defining entity types and relations
Tuples	Relationship data stored in the model schema

Keymate uses a store-per-tenant model: each tenant receives a dedicated OpenFGA store, providing complete isolation of authorization data between tenants.

Authorization Model Structure

OpenFGA authorization models define the relationship schema:

type user

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

This model defines:

• A document entity type
• Three relations: owner, editor, viewer
• Inheritance: owner implies editor, editor implies viewer

API Operations

The FGA Engine uses these OpenFGA API operations:

Operation	Endpoint	Purpose
Check	POST /stores/{store}/check	Verify relationship exists
Write	POST /stores/{store}/write	Create or delete tuples
Read	POST /stores/{store}/read	Query existing tuples
ListObjects	POST /stores/{store}/list-objects	Find accessible objects
ListUsers	POST /stores/{store}/list-users	Find users with access

Check Request Flow

When evaluating a ReBAC policy:

1. FGA Engine extracts user, relation, and object from the request
2. FGA Engine sends check request to OpenFGA
3. OpenFGA loads the authorization model
4. OpenFGA traverses the relationship graph
5. OpenFGA returns allowed: true or allowed: false

Configuration

The FGA Engine requires these configuration parameters to connect to OpenFGA:

Parameter	Description
API URL	OpenFGA service endpoint (HTTP or gRPC)
Store ID	Identifier for the OpenFGA store
Authorization Model ID	Version of the authorization model to use
TLS Enabled	Enable TLS for production deployments
Authentication Token	Pre-shared token for API authentication (if enabled)

note

For production deployments, enable TLS and API authentication. See Deployment Model for security configuration details.

Diagram

Example Scenario

Scenario

A user attempts to delete a document. The FGA Engine queries OpenFGA to verify if the user has owner access through team membership.

Input

• Actor: FGA Engine processing ReBAC policy
• Resource: Check if user:bob@example.com has owner relation to document:budget-2024
• Action: Authorization check (delete requires owner)
• Context: Bob is a member of team:finance, which has editor access to the document

Expected Outcome

• OpenFGA receives check request for owner relation
• Graph traversal finds: user:bob → member → team:finance → editor → document:budget-2024
• However, editor does not imply owner in the model (only owner implies editor)
• OpenFGA returns allowed: false
• FGA Engine denies the delete operation

This demonstrates how the authorization model enforces permission boundaries—team members can edit but not delete documents unless explicitly granted owner access.

Common Misunderstandings

• OpenFGA stores user credentials — OpenFGA stores only relationship tuples, not identity data. User information remains in the identity provider.
• Each check creates a new connection — The FGA Engine maintains a connection pool to OpenFGA, reusing connections across requests for low-latency queries.
• Tuple format is (source, relation, target) — OpenFGA uses (user, relation, object) terminology. The "user" can be any entity (user, group, or object with a relation).

warning

Authorization model changes can affect existing tuple interpretations. Test model updates thoroughly before deploying to production.

Design Notes / Best Practices

• Version authorization models and track changes
• Use relationship inheritance to reduce tuple storage
• Monitor OpenFGA query latency and error rates
• Implement tuple lifecycle management (create/delete) in application workflows

tip

Use OpenFGA's expand API during debugging to visualize the relationship paths evaluated for a check request.

Related Use Cases

• Per-document access control with owner/editor/viewer relations
• Team-based resource access through membership tuples
• Organization hierarchy with inherited permissions

Related Docs

FGA Backend Overview

Relationship storage and evaluation layer

Deployment Model

OpenFGA deployment patterns

FGA Engine

Platform component for ReBAC

ReBAC

Relationship-based authorization model