OpenFGA is a high-performance, open-source authorization engine inspired by Google's Zanzibar paper. It provides a fine-grained access control system that allows applications to determine whether a user has a specific relation to an object, discover all objects a user can access, and find all users who have access to an object. This page provides a high-level introduction to OpenFGA's architecture, core capabilities, and technology stack.
For detailed information about specific subsystems, see:
Sources: README.md23-24 CHANGELOG.md1-8
OpenFGA implements relationship-based access control (ReBAC) through three primary APIs:
| API | Purpose | Use Case |
|---|---|---|
| Check | Verify if a user has a relation to an object | "Can user X view document Y?" |
| ListObjects | Find all objects a user can access | "What documents can user X view?" |
| ListUsers | Find all users with access to an object | "Who can view document Y?" |
These APIs operate on relationship tuples (user, relation, object) stored in the system and evaluate them against an authorization model that defines how relations compose and inherit. Recent updates include experimental support for the AuthZEN 1.0 standard and a high-performance weighted_graph_check resolution strategy which has been extended to BatchCheck CHANGELOG.md13-14
Sources: README.md23-36 CHANGELOG.md13-14 CHANGELOG.md38-39
The following diagram shows the high-level architecture from clients to storage, illustrating how requests flow through gateway layers into core authorization APIs:
The architecture follows a layered design where API requests flow through gateway layers into core authorization APIs. Storage is abstracted to support multiple backends, with SQL implementations sharing a common logic layer.
Sources: README.md26-36 CHANGELOG.md18 CHANGELOG.md72-73
OpenFGA exposes both HTTP and gRPC interfaces. The HTTP server uses grpc-gateway to translate HTTP requests to gRPC calls.
Recent updates improved system performance by implementing TLV (type-length-value) binary encoding for cache keys to eliminate collision risks and adding per-process hash seeding to prevent hash-flooding attacks CHANGELOG.md41-42
Sources: README.md86-92 CHANGELOG.md41-42 CHANGELOG.md72-73
The core engine implements graph-based relationship resolution. The following diagram bridges system concepts to code entities:
Key components with their code locations:
cmd/openfga/main.go, it orchestrates the root command and subcommands like run and migrate cmd/openfga/main.go13-27internal/listobjects/pipeline): High-performance ListObjects implementation which supports edge pruning for larger, more complex authorization models CHANGELOG.md72-73pkg/typesystem/typesystem.go): Validates authorization models and provides type-safe access to model definitions.Check resolution. It now includes diagnostic logging when v2 resolution differs from v1 CHANGELOG.md10-11Sources: CHANGELOG.md72-73 cmd/openfga/main.go13-27 CHANGELOG.md10-11
OpenFGA provides a pluggable storage abstraction.
| Implementation | Description |
|---|---|
| PostgreSQL | Production-ready. Supports pgxpool and connection pooling go.mod28 |
| MySQL | Production-ready SQL backend. Recent security fixes enforced case-sensitive identifier comparison CHANGELOG.md20-21 |
| SQLite | Beta support for embedded use cases README.md29 |
| In-Memory | For development and testing only README.md68-72 |
The storage layer includes shared logic to minimize duplication across SQL dialects. The system now supports configurable datastore ping timeouts and retry strategies CHANGELOG.md56-57
Sources: README.md29 CHANGELOG.md20-21 CHANGELOG.md56-57
OpenFGA is built using the following core technologies:
Sources: go.mod1-61 CHANGELOG.md38-39 CHANGELOG.md34-35
For deeper exploration of specific areas:
Sources: README.md40-53