github.com/openfga/openfga@v1.5.4-rc1/README.md (about) 1 # OpenFGA 2 3 [](https://pkg.go.dev/github.com/openfga/openfga) 4  5 [](https://hub.docker.com/r/openfga/openfga/tags) 6 [](https://app.codecov.io/gh/openfga/openfga) 7 [](https://goreportcard.com/report/github.com/openfga/openfga) 8 [](https://bestpractices.coreinfrastructure.org/projects/6374) 9 [](https://openfga.dev/community) 10 [](https://twitter.com/openfga) 11 [](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenfga%2Fopenfga?ref=badge_shield) 12 [](https://artifacthub.io/packages/helm/openfga/openfga) 13 [](https://securityscorecards.dev/viewer/?uri=github.com/openfga/openfga) 14 [](https://slsa.dev) 15 16 A high-performance and flexible authorization/permission engine built for developers and inspired by [Google Zanzibar](https://research.google/pubs/pub48190/). 17 18 OpenFGA is designed to make it easy for developers to model their application permissions and add and integrate fine-grained authorization into their applications. 19 20 It allows in-memory data storage for quick development, as well as pluggable database modules. It currently supports PostgreSQL 14 and MySQL 8. 21 22 It offers an [HTTP API](https://openfga.dev/api/service) and a [gRPC API](https://buf.build/openfga/api/file/main:openfga/v1/openfga_service.proto). It has SDKs for [Java](https://central.sonatype.com/artifact/dev.openfga/openfga-sdk), [Node.js/JavaScript](https://www.npmjs.com/package/@openfga/sdk), [GoLang](https://github.com/openfga/go-sdk), [Python](https://github.com/openfga/python-sdk) and [.NET](https://www.nuget.org/packages/OpenFga.Sdk). Look in our [Community section](https://github.com/openfga/community#community-projects) for third-party SDKs and tools. It can also be used as a library (see [example](https://pkg.go.dev/github.com/openfga/openfga/pkg/server#pkg-examples)). 23 24 ## Getting Started 25 26 The following section aims to help you get started quickly. Please look at our official [documentation](https://openfga.dev/) for in-depth information. 27 28 ### Setup and Installation 29 30 > ℹ️ 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. 31 > 32 > For more information on how to configure the OpenFGA server, please take a look at our official documentation on [Running in Production](https://openfga.dev/docs/getting-started/running-in-production). 33 34 #### Docker 35 36 OpenFGA is available on [Dockerhub](https://hub.docker.com/r/openfga/openfga), so you can quickly start it using the in-memory datastore by running the following commands: 37 38 ```bash 39 docker pull openfga/openfga 40 docker run -p 8080:8080 -p 3000:3000 openfga/openfga run 41 ``` 42 43 > [!TIP] 44 > The `OPENFGA_HTTP_ADDR` environment variable can used to configure the address at which [the playground](https://openfga.dev/docs/getting-started/setup-openfga/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 run` will start the OpenFGA server on port 4000, and configure the playground too. 45 46 #### Docker Compose 47 48 [`docker-compose.yaml`](./docker-compose.yaml) provides an example of how to launch OpenFGA with Postgres using `docker compose`. 49 50 1. First, either clone this repo or curl the `docker-compose.yaml` file with the following command: 51 52 ```bash 53 curl -LO https://openfga.dev/docker-compose.yaml 54 ``` 55 56 2. Then, run the following command: 57 58 ```bash 59 docker compose up 60 ``` 61 62 ### Package Managers 63 64 If you are a [Homebrew](https://brew.sh/) user, you can install [OpenFGA](https://formulae.brew.sh/formula/openfga) with the following command: 65 66 ```bash 67 brew install openfga 68 ``` 69 70 #### Pre-compiled Binaries 71 72 Download your platform's [latest release](https://github.com/openfga/openfga/releases/latest) and extract it. Then run the binary 73 with the command: 74 75 ```bash 76 ./openfga run 77 ``` 78 79 ### Building from Source 80 81 There are two recommended options for building OpenFGA from source code: 82 83 #### Building from source with `go install` 84 85 > Make sure you have Go 1.20 or later installed. See the [Go downloads](https://go.dev/dl/) page. 86 87 You can install from source using Go modules: 88 89 1. First, make sure `$GOBIN` is on your shell `$PATH`: 90 91 ```bash 92 export PATH=$PATH:$(go env GOBIN) 93 ``` 94 95 2. Then use the install command: 96 97 ```bash 98 go install github.com/openfga/openfga/cmd/openfga 99 ``` 100 101 3. Run the server with: 102 103 ```bash 104 ./openfga run 105 ``` 106 107 #### Building from source with `go build` 108 109 Alternatively you can build OpenFGA by cloning the project from this Github repo, and then building it with the `go build` command: 110 111 1. Clone the repo to a local directory, and navigate to that directory: 112 113 ```bash 114 git clone https://github.com/openfga/openfga.git && cd openfga 115 ``` 116 117 2. Then use the build command: 118 119 ```bash 120 go build -o ./openfga ./cmd/openfga 121 ``` 122 123 3. Run the server with: 124 125 ```bash 126 ./openfga run 127 ``` 128 129 ### Verifying the Installation 130 131 Now that you have [Set up and Installed](#setup-and-installation) OpenFGA, you can test your installation by [creating an OpenFGA Store](https://openfga.dev/docs/getting-started/create-store). 132 133 ```bash 134 curl -X POST 'localhost:8080/stores' \ 135 --header 'Content-Type: application/json' \ 136 --data-raw '{ 137 "name": "openfga-demo" 138 }' 139 ``` 140 141 If everything is running correctly, you should get a response with information about the newly created store, for example: 142 143 ```json 144 { 145 "id": "01G3EMTKQRKJ93PFVDA1SJHWD2", 146 "name": "openfga-demo", 147 "created_at": "2022-05-19T17:11:12.888680Z", 148 "updated_at": "2022-05-19T17:11:12.888680Z" 149 } 150 ``` 151 152 ## Playground 153 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. 154 155 To run OpenFGA with the Playground disabled, provide the `--playground-enabled=false` flag. 156 157 ``` 158 ./openfga run --playground-enabled=false 159 ``` 160 Once OpenFGA is running, by default, the Playground can be accessed at [http://localhost:3000/playground](http://localhost:3000/playground). 161 162 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, 163 164 ```sh 165 ./openfga run --playground-enabled --playground-port 3001 166 ``` 167 168 ## Profiler (pprof) 169 Profiling through [pprof](https://github.com/google/pprof) can be enabled on the OpenFGA server by providing the `--profiler-enabled` flag. 170 171 ```sh 172 ./openfga run --profiler-enabled 173 ``` 174 175 This will start serving profiling data on port `3001`. You can see that data by visiting `http://localhost:3001/debug/pprof`. 176 177 If you need to serve the profiler on a different address, you can do so by specifying the `--profiler-addr` flag. For example, 178 179 ```sh 180 ./openfga run --profiler-enabled --profiler-addr :3002 181 ``` 182 183 Once the OpenFGA server is running, in another window you can run the following command to generate a compressed CPU profile: 184 185 ```sh 186 go tool pprof -proto -seconds 60 http://localhost:3001/debug/pprof/profile 187 # will collect data for 60 seconds and generate a file like pprof.samples.cpu.001.pb.gz 188 ``` 189 190 That file can be analyzed visually by running the following command and then visiting `http://localhost:8084`: 191 192 ```shell 193 go tool pprof -http=localhost:8084 pprof.samples.cpu.001.pb.gz 194 ``` 195 196 ## Next Steps 197 198 Take a look at examples of how to: 199 200 - [Write an Authorization Model](https://openfga.dev/api/service#/Authorization%20Models/WriteAuthorizationModel) 201 - [Write Relationship Tuples](https://openfga.dev/api/service#/Relationship%20Tuples/Write) 202 - [Perform Authorization Checks](https://openfga.dev/api/service#/Relationship%20Queries/Check) 203 - [Add Authentication to your OpenFGA server](https://openfga.dev/docs/getting-started/setup-openfga/docker#configuring-authentication) 204 205 Don't hesitate to browse the official [Documentation](https://openfga.dev/), [API Reference](https://openfga.dev/api/service). 206 207 ## Limitations 208 ### MySQL Storage engine 209 The MySQL storage engine has a lower length limit for some properties of a tuple compared with other storage backends. For more information see [the docs](https://openfga.dev/docs/getting-started/setup-openfga/docker#configuring-data-storage). 210 211 OpenFGA's MySQL Storage Adapter was contributed to OpenFGA by [@twintag](https://github.com/twintag). Thanks! 212 213 ## Production Readiness 214 215 The core [OpenFGA](https://github.com/openfga/openfga) service has been in use by [Okta FGA](https://fga.dev) in production since December 2021. 216 217 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. 218 219 You can learn about more organizations using OpenFGA in production [here](https://github.com/openfga/community/blob/main/ADOPTERS.md). If your organization is using OpenFGA in production please consider adding it to the list. 220 221 The OpenFGA team will do its best to address all production issues with high priority. 222 223 ## Contributing 224 225 See [CONTRIBUTING](https://github.com/openfga/.github/blob/main/CONTRIBUTING.md). 226 227 [doc]: https://openfga.dev/docs 228 [config-doc]: https://openfga.dev/docs/getting-started/setup-openfga/configure-openfga 229 [api]: https://openfga.dev/api/service 230 [prod-checklist]: https://openfga.dev/docs/getting-started/running-in-production 231 232 ## Community Meetings 233 234 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 [here](https://github.com/openfga/community/blob/main/community-meetings.md).