README
¶
OpenFGA
OpenFGA is a high-performance, flexible authorization/permission engine inspired by Google Zanzibar. It helps developers easily model and enforce fine-grained access control in their applications.
Highlights
- ⚡ High-performance, developer-friendly APIs (HTTP & gRPC)
- 🔌 Flexible storage backends (In-Memory, PostgreSQL, MySQL, SQLite beta)
- 🧰 SDKs for Java, Node.js, Go, Python, .NET
- 🌐 Several additional SDKs and tools contributed by the community
- 🧪 CLI for interacting with an OpenFGA server and testing authorization models
- 🌿 Terraform Provider for configuring OpenFGA servers as code
- 🎮 Playground for modeling and testing
- 🛠 Can also be embedded as a Go library
- 🤝 Adopted by Auth0, Grafana Labs, Canonical, Docker, Agicap, Read.AI and others
Table of Contents
- Quickstart
- Installation
- Playground
- Next Steps
- Limitations
- Production Readiness
- Contributing & Community
Quickstart
[!IMPORTANT]
The following steps are meant for quick local setup and evaluation.
When using the default in-memory storage engine, data is ephemeral and will be discarded once the service stops.For details on configuring storage backends, tuning performance, and deploying OpenFGA securely in production-ready environments, refer to the documentation: Running in Production.
Run OpenFGA with in-memory storage (⚠️ not for production):
docker run -p 8080:8080 -p 3000:3000 openfga/openfga run
Once running, create a store:
curl -X POST 'localhost:8080/stores' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "openfga-demo"}'
Installation
Docker
OpenFGA is available on Docker Hub, so you can quickly start it using the in-memory datastore by running the following commands:
docker pull openfga/openfga
docker run -p 8080:8080 -p 3000:3000 openfga/openfga run
Docker Compose
docker-compose.yaml provides an example of how to launch OpenFGA with Postgres using docker compose.
curl -LO https://openfga.dev/docker-compose.yaml
docker compose up
Homebrew
If you are a Homebrew user, you can install OpenFGA with the following command:
brew install openfga
Precompiled Binaries
Download your platform's latest release and extract it. Then run the binary with the command:
./openfga run
Build from Source
[!NOTE]
Make sure you have the latest version of Go installed. See the Go downloads page.
go install
export PATH=$PATH:$(go env GOBIN) # make sure $GOBIN is on your $PATH
go install github.com/openfga/openfga/cmd/openfga
openfga run
go build
git clone https://github.com/openfga/openfga.git && cd openfga
go build -o ./openfga ./cmd/openfga
./openfga run
Verify Installation
Now that you have installed OpenFGA, you can test your installation by creating an OpenFGA Store.
curl -X POST 'localhost:8080/stores' \
--header 'Content-Type: application/json' \
--data-raw '{"name": "openfga-demo"}'
If everything is running correctly, you should get a response with information about the newly created store, for example:
{
"id": "01G3EMTKQRKJ93PFVDA1SJHWD2",
"name": "openfga-demo",
"created_at": "2022-05-19T17:11:12.888680Z",
"updated_at": "2022-05-19T17:11:12.888680Z"
}
Playground
The Playground lets you model, visualize, and test authorization setups. By default, it’s available at: http://localhost:3000/playground
[!NOTE]
The Playground is intended for local development only.
It can currently only be configured to connect to an OpenFGA server running onlocalhost.
Disable it with:
./openfga run --playground-enabled=false
Change port:
./openfga run --playground-enabled --playground-port 3001
[!TIP] The
OPENFGA_HTTP_ADDRenvironment variable can be used to configure the address at which the Playground expects the OpenFGA server to be.For example:
docker run -e OPENFGA_PLAYGROUND_ENABLED=true \ -e OPENFGA_HTTP_ADDR=0.0.0.0:4000 \ -p 4000:4000 -p 3000:3000 openfga/openfga runThis starts OpenFGA on port 4000 and configures the Playground accordingly.
Next Steps
Take a look at examples of how to:
- Write an Authorization Model
- Write Relationship Tuples
- Perform Authorization Checks
- Add Authentication to your OpenFGA server
📚 Explore the Documentation and API Reference.
Limitations
MySQL Storage engine
The MySQL storage engine has stricter length limits on tuple properties than other backends. See docs.
💡 OpenFGA’s MySQL adapter was contributed by @twintag — thank you!
Production Readiness
- ✅ Used in production by Auth0 FGA since December 2021
- ⚠️ Memory storage adapter is for development only
- 🗄 Supported storage: PostgreSQL 14+, MySQL 8, SQLite (beta)
- 📘 See Running in Production
The OpenFGA team treats production-impacting issues with highest priority.
See organizations using OpenFGA in production: ADOPTERS.md. If your organization is using OpenFGA, please consider adding it to the list.
Contributing & Community
We welcome contributions and community participation.
- 🤝 See CONTRIBUTING
- 🗓 Monthly Community Meetings
- 💬 Join us on Slack
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets contains database migration scripts and test files
|
Package assets contains database migration scripts and test files |
|
Package cmd contains all the commands included in the binary file.
|
Package cmd contains all the commands included in the binary file. |
|
migrate
Package migrate contains the command to perform database migrations.
|
Package migrate contains the command to perform database migrations. |
|
openfga
command
Package main contains the root of all commands.
|
Package main contains the root of all commands. |
|
run
Package run contains the command to run an OpenFGA server.
|
Package run contains the command to run an OpenFGA server. |
|
util
Package util provides common utilities for spf13/cobra CLI utilities that can be used for various commands within this project.
|
Package util provides common utilities for spf13/cobra CLI utilities that can be used for various commands within this project. |
|
validatemodels
Package validatemodels contains the command to run validations on authorization models.
|
Package validatemodels contains the command to run validations on authorization models. |
|
internal
|
|
|
build
Package build provides build information that is linked into the application.
|
Package build provides build information that is linked into the application. |
|
condition/metrics
Package metrics provides various metric and telemetry definitions for OpenFGA Conditions.
|
Package metrics provides various metric and telemetry definitions for OpenFGA Conditions. |
|
graph
Package graph contains code related to evaluation of authorization models through graph traversals.
|
Package graph contains code related to evaluation of authorization models through graph traversals. |
|
mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
utils/apimethod
Package apimethod provides a type for the API grpc method names.
|
Package apimethod provides a type for the API grpc method names. |
|
pkg
|
|
|
encoder
Package encoder provides implementations for data encoding and continuation token encoding.
|
Package encoder provides implementations for data encoding and continuation token encoding. |
|
encrypter
Package encrypter contains data encryption implementations.
|
Package encrypter contains data encryption implementations. |
|
gateway
Package gateway provides implementations to send data through the transport (e.g.
|
Package gateway provides implementations to send data through the transport (e.g. |
|
logger
Package logger contains logging implementations.
|
Package logger contains logging implementations. |
|
middleware/http
Package http contains middleware and utility functions to modify HTTP requests and responses.
|
Package http contains middleware and utility functions to modify HTTP requests and responses. |
|
middleware/logging
Package logging contains logging middleware.
|
Package logging contains logging middleware. |
|
middleware/requestid
Package requestid contains middleware to inject and manage request id context.
|
Package requestid contains middleware to inject and manage request id context. |
|
middleware/storeid
Package storeid contains middleware to inject and manage the store ID context.
|
Package storeid contains middleware to inject and manage the store ID context. |
|
middleware/validator
Package validator contains middleware that validates API input parameters.
|
Package validator contains middleware that validates API input parameters. |
|
server
Package server contains the endpoint handlers.
|
Package server contains the endpoint handlers. |
|
server/commands
Package commands contains the code that handles each endpoint.
|
Package commands contains the code that handles each endpoint. |
|
server/commands/reverseexpand
Package reverseexpand contains the code that handles the ReverseExpand API
|
Package reverseexpand contains the code that handles the ReverseExpand API |
|
server/config
Package config contains all knobs and defaults used to configure features of OpenFGA when running as a standalone server.
|
Package config contains all knobs and defaults used to configure features of OpenFGA when running as a standalone server. |
|
server/errors
Package errors contains custom error codes that are sent to clients.
|
Package errors contains custom error codes that are sent to clients. |
|
server/health
Package health contains the service that check the health of an OpenFGA server.
|
Package health contains the service that check the health of an OpenFGA server. |
|
storage
Package storage contains storage interfaces and implementations.
|
Package storage contains storage interfaces and implementations. |
|
storage/memory
Package memory contains an implementation of the storage interface that lives in memory.
|
Package memory contains an implementation of the storage interface that lives in memory. |
|
storage/mysql
Package mysql contains an implementation of the storage interface that works with MySQL.
|
Package mysql contains an implementation of the storage interface that works with MySQL. |
|
storage/postgres
Package postgres contains an implementation of the storage interface that works with Postgres.
|
Package postgres contains an implementation of the storage interface that works with Postgres. |
|
storage/sqlcommon
Package sqlcommon contains utility functions shared among all SQL data stores.
|
Package sqlcommon contains utility functions shared among all SQL data stores. |
|
storage/sqlite
Package sqlite contains an implementation of the storage interface that works with SQLite.
|
Package sqlite contains an implementation of the storage interface that works with SQLite. |
|
storage/storagewrappers
Package storagewrappers contains decorators for storage implementations.
|
Package storagewrappers contains decorators for storage implementations. |
|
telemetry
Package telemetry contains code that emits telemetry (logging, metrics, tracing).
|
Package telemetry contains code that emits telemetry (logging, metrics, tracing). |
|
testfixtures/storage
Package storage contains containers that can be used to test all available data stores.
|
Package storage contains containers that can be used to test all available data stores. |
|
testutils
Package testutils contains code that is useful in tests.
|
Package testutils contains code that is useful in tests. |
|
tuple
Package tuple contains code to manipulate tuples and errors related to tuples.
|
Package tuple contains code to manipulate tuples and errors related to tuples. |
|
typesystem
Package typesystem contains code to manipulate authorization models.
|
Package typesystem contains code to manipulate authorization models. |
|
check
Package check contains integration tests for the query APIs (ListObjects, ListUsers and Check)
|
Package check contains integration tests for the query APIs (ListObjects, ListUsers and Check) |
|
listobjects
Package listobjects contains integration tests for the ListObjects and StreamedListObjects APIs.
|
Package listobjects contains integration tests for the ListObjects and StreamedListObjects APIs. |
|
listusers
Package listusers contains integration tests for the ListUsers and StreamedListUsers APIs.
|
Package listusers contains integration tests for the ListUsers and StreamedListUsers APIs. |