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
  • Docker
  • Docker Compose
  • Homebrew
  • Precompiled Binaries
  • Build from Source
  • Verify 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

[!NOTE] When the HTTP server is enabled, it will attempt to establish an internal client connection to the gRPC server via unix domain socket. When it is not possible to establish a UDS, the client connection automatically falls back to using a TCP socket.

If running the Docker image using the --read-only option, the --tmpfs option must also be set in order to enabled use of the unix domain socket. For example --tmpfs /tmp

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 on localhost.

Disable it with:

./openfga run --playground-enabled=false

Change port:

./openfga run --playground-enabled --playground-port 3001

[!TIP] The OPENFGA_HTTP_ADDR environment variable can be used to configure the address at which the Playground expects the OpenFGA server to be.

For example:

shell docker run -e OPENFGA_PLAYGROUND_ENABLED=true \ -e OPENFGA_HTTP_ADDR=0.0.0.0:4000 \ -p 4000:4000 -p 3000:3000 openfga/openfga run

This 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