Project: OpenFGA (Provisioning / Security & Compliance)
File: README.md

](https://pkg.go.dev/github.com/openfga/openfga) ](https://hub.docker.com/r/openfga/openfga/tags) ](https://app.codecov.io/gh/openfga/openfga) ](https://goreportcard.com/report/github.com/openfga/openfga) ](https://bestpractices.coreinfrastructure.org/projects/6374) ](https://openfga.dev/community) ](https://twitter.com/openfga) ](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenfga%2Fopenfga?ref=badge_shield) ](https://artifacthub.io/packages/helm/openfga/openfga) ](https://securityscorecards.dev/viewer/?uri=github.com/openfga/openfga) ](https://slsa.dev) A high-performance and flexible authorization/permission engine built for developers and inspired by . OpenFGA is designed to make it easy for developers to model their application permissions and add and integrate fine-grained authorization into their applications. It allows in-memory data storage for quick development, as well as pluggable database modules. It currently supports PostgreSQL 14 and MySQL 8. It offers an and a . It has SDKs for , , , and . Look in our for third-party SDKs and tools. It can also be used as a library (see ). The following section aims to help you get started quickly. Please look at our official for in-depth information. The following sections setup an OpenFGA server using the default configuration values. These are for rapid development and not for a production environment. Data written to an OpenFGA instance using the default configuration with the memory storage engine will not persist after the service is stopped. For more information on how to configure the OpenFGA server, please take a look at our official documentation on . OpenFGA is available on , so you can quickly start it using the in-memory datastore by running the following commands: ```bash docker pull openfga/openfga docker run -p 8080:8080 -p 3000:3000 openfga/openfga run ``` [!TIP] The `OPENFGAHTTPADDR` environment variable can used to configure the address at which expects the OpenFGA server to be. For example, `docker run -e OPENFGAPLAYGROUNDENABLED=true -e OPENFGAHTTPADDR=0.0.0.0:4000 -p 4000:4000 -p 3000:3000 openfga/openfga run` will start the OpenFGA server on port 4000, and configure the playground too. provides an example of how to launch OpenFGA with Postgres using `docker compose`. First, either clone this repo or curl the `docker-compose.yaml` file with the following command: ```bash curl -LO https://openfga.dev/docker-compose.yaml ``` Then, run the following command: ```bash docker compose up ``` If you are a user, you can install with the following command: ```bash brew install openfga ``` Download your platform's and extract it. Then run the binary with the command: ```bash ./openfga run ``` There are two recommended options for building OpenFGA from source code: Make sure you have Go 1.20 or later installed. See the page. You can install from source using Go modules: First, make sure `$GOBIN` is on your shell `$PATH`: ```bash export PATH=$PATH:$(go env GOBIN) ``` Then use the install command: ```bash go install github.com/openfga/openfga/cmd/openfga ``` Run the server with: ```bash ./openfga run ``` Alternatively you can build OpenFGA by cloning the project from this Github repo, and then building it with the `go build` command: Clone the repo to a local directory, and navigate to that directory: ```bash git clone

&& cd openfga ``` Then use the build command: ```bash go build -o ./openfga ./cmd/openfga ``` Run the server with: ```bash ./openfga run ``` Now that you have OpenFGA, you can test your installation by . ```bash 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: ```json { "id": "01G3EMTKQRKJ93PFVDA1SJHWD2", "name": "openfga-demo", "created_at": "2022-05-19T17:11:12.888680Z", "updated_at": "2022-05-19T17:11:12.888680Z" } ``` The Playground facilitates rapid development by allowing you to visualize and model your application's authorization model(s) and manage relationship tuples with a locally running OpenFGA instance. To run OpenFGA with the Playground disabled, provide the `--playground-enabled=false` flag. ``` ./openfga run --playground-enabled=false ``` Once OpenFGA is running, by default, the Playground can be accessed at . In the event that a port other than the default port is required, the `--playground-port` flag can be set to change it. For example, ```sh ./openfga run --playground-enabled --playground-port 3001 ``` Profiling through can be enabled on the OpenFGA server by providing the `--profiler-enabled` flag. ```sh ./openfga run --profiler-enabled ``` This will start serving profiling data on port `3001`. You can see that data by visiting `http://localhost:3001/debug/pprof`. If you need to serve the profiler on a different address, you can do so by specifying the `--profiler-addr` flag. For example, ```sh ./openfga run --profiler-enabled --profiler-addr :3002 ``` Once the OpenFGA server is running, in another window you can run the following command to generate a compressed CPU profile: ```sh go tool pprof -proto -seconds 60 http://localhost:3001/debug/pprof/profile ``` That file can be analyzed visually by running the following command and then visiting `http://localhost:8084`: ```shell go tool pprof -http=localhost:8084 pprof.samples.cpu.001.pb.gz ``` Take a look at examples of how to: Don't hesitate to browse the official , . The MySQL storage engine has a lower length limit for some properties of a tuple compared with other storage backends. For more information see . OpenFGA's MySQL Storage Adapter was contributed to OpenFGA by . Thanks! The core service has been in use by in production since December 2021. OpenFGA's Memory Storage Adapter was built for development purposes only and is not recommended for a production environment, because it is not designed for scalable queries and has no support for persistence. You can learn about more organizations using OpenFGA in production . If your organization is using OpenFGA in production please consider adding it to the list. The OpenFGA team will do its best to address all production issues with high priority. See . We hold a monthly meeting to interact with the community, collaborate and receive/provide feedback. You can find more details, including the time, our agenda, and the meeting minutes .