openfga / api

Protocol Buffers used by OpenFGA

OpenFGA

A high-performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.

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 HTTP API and a gRPC API. It has SDKs for Java, Node.js/JavaScript, GoLang, Python and .NET. Look in our Community section for third-party SDKs and tools. It can also be used as a library (see example).

Getting Started

The following section aims to help you get started quickly. Please look at our official documentation for in-depth information.

Setup and Installation

ℹ️ 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 Running in Production.

Docker

OpenFGA is available on Dockerhub, 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

Tip

The OPENFGA_HTTP_ADDR environment variable can 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 run will start the OpenFGA server on port 4000, and configure the playground too.

Docker Compose

docker-compose.yaml provides an example of how to launch OpenFGA with Postgres using docker compose.

1. First, either clone this repo or curl the docker-compose.yaml file with the following command:

   curl -LO https://openfga.dev/docker-compose.yaml

2. Then, run the following command:

   docker compose up

Package Managers

If you are a Homebrew user, you can install OpenFGA with the following command:

brew install openfga

Pre-compiled Binaries

Download your platform's latest release and extract it. Then run the binary with the command:

./openfga run

Building from Source

There are two recommended options for building OpenFGA from source code:

Building from source with go install

Make sure you have Go 1.20 or later installed. See the Go downloads page.

You can install from source using Go modules:

1. First, make sure $GOBIN is on your shell $PATH:

   export PATH=$PATH:$(go env GOBIN)

2. Then use the install command:

   go install github.com/openfga/openfga/cmd/openfga

3. Run the server with:

   ./openfga run

Building from source with go build

Alternatively you can build OpenFGA by cloning the project from this Github repo, and then building it with the go build command:

1. Clone the repo to a local directory, and navigate to that directory:

   git clone https://github.com/openfga/openfga.git && cd openfga

2. Then use the build command:

   go build -o ./openfga ./cmd/openfga

3. Run the server with:

   ./openfga run

Verifying the Installation

Now that you have Set up and 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 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 http://localhost:3000/playground.

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,

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

Profiler (pprof)

Profiling through pprof can be enabled on the OpenFGA server by providing the --profiler-enabled flag.

./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,

./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:

go tool pprof -proto -seconds 60 http://localhost:3001/debug/pprof/profile
# will collect data for 60 seconds and generate a file like pprof.samples.cpu.001.pb.gz

That file can be analyzed visually by running the following command and then visiting http://localhost:8084:

go tool pprof -http=localhost:8084 pprof.samples.cpu.001.pb.gz

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

Don't hesitate to browse the official Documentation, API Reference.

Limitations

MySQL Storage engine

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.

OpenFGA's MySQL Storage Adapter was contributed to OpenFGA by @twintag. Thanks!

Production Readiness

The core OpenFGA service has been in use by Okta FGA 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 here. 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.

Contributing

See CONTRIBUTING.

Community Meetings

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.

api's Issues

Documentation for Read is missing some of the cases

Generate OpenAPI v3 definitions for the http API

There are some tools like https://www.thunderclient.com/ that don't work with our current swagger definitions.

A new section can be added to this script to convert this openapiv2 file to openapiv3 and place it in /docs/openapiv3/apidocs.swagger.json

Write API: make TupleKeys more canonical

Today the Write API looks like:

message WriteRequest {
    string store_id = 1;
    TupleKeys writes = 2;
    TupleKeys deletes = 3;
    string authorization_model_id = 4;
}

message TupleKeys {
    repeated TupleKey tuple_keys = 1;
}

message TupleKey {
    string object = 1;
    string relation = 2;
    string user = 3;
}

The usage of TupleKeys is completely unnecessary and makes the API and related code stutter. For example in Go code we have:

tupleKeys := openfgapb.TupleKeys{
    TupleKeys: []*openfgapb.TupleKey{...}
}

I propose we make this more canonical with simply:

message WriteRequest {
    string store_id = 1;
    repeated TupleKey writes = 2;
    repeated TupleKey deletes = 3;
    string authorization_model_id = 4;
}

and the corresponding code in Go will simply look like:

tupleKeys := []*openfgapb.TupleKey{...}

Note that these changes are a breaking change to the API though. The HTTP request body and gRPC request bodies change in an incompatible way.

{
    "writes": {
        "tuple_keys": [...]
    },
    "deletes": {
        "tuple_keys": [...]
    }
}

becomes

{
    "writes": [...],
    "deletes": [...]
}

Wrong status code successful CreateStore

Currently, the HTTP status code for a successful is listed as 200 in the swagger file (

api/docs/openapiv2/apidocs.swagger.json

Line 82 in 05fefe3

"200": {

). However, in reality, the openfga server will respond with 201 (https://github.com/openfga/openfga/blob/b808e7eac066c725d535b046b53fae5d58d8bb0f/server/server.go#L337).

We need to update the proto file to reflect the fact that the response code is 201, not 200

Add documentation that empty continuation token means last page

Currently, there is no note on our swagger that empty continuation token means the last page (except read changes). As noted in openfga/go-sdk#38 (comment), it will be good to have documentation on that.

Increase contextual tuples limit to 20

Character # and @ should be disallowed for type and relation name

The character # and @ should be disallowed for type and relation name. Otherwise, it will cause confusion when evaluate for check. Note that # is used to indicate tuple to userset.

Support Modular Models

As mentioned in our Modular Models RFC, we need to add support for module and file in the type and relation metadata, as well as in condition

Create Protobufs for ResolveCheckRequest and ResolveCheckResponse

Originally posted by @jon-whit in openfga/openfga#880 (comment)

list object user field must be non empty string for list object

Need to enforce that user field for list object must be non-empty

Is it possible to provide an interface for batch checking, e.g. BatchCheck?

Document protobufs in favor of OpenAPI

Originally posted by @jon-whit in #83 (comment)

Currently the documentations are OpenAPI based, we should consider moving/adding it to protobufs

feat(listObjects): ListObjects API proposed changes

ListObjects API

Roadmap Issue: openfga/roadmap#8

Summary

This issue serves as a proposal for the API changes to support the OpenFGA ListObjects API as described in openfga/roadmap#8.

Proposed Changes

The proposed changes to the OpenFGA APIs (contained herein) are outlined in openfga/rfcs#3

If anyone has any opinions or recommendations we'd love to hear them!

Incorrect example for read authorization models

The example listed in read authorization models is incorrect. Currently, it reads

{
  "authorization_models": [
    {
      "id": "01G50QVV17PECNVAHX1GG4Y5NC",
      "type_definitions": [...]
    },
    {
      "id": "01G4ZW8F4A07AKQ8RHSVG9RW04",
      "type_definitions": [...]
    },
  ]
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}

Notice there is a missing comma before continuation token. Instead, it should be

{
  "authorization_models": [
    {
      "id": "01G50QVV17PECNVAHX1GG4Y5NC",
      "type_definitions": [...]
    },
    {
      "id": "01G4ZW8F4A07AKQ8RHSVG9RW04",
      "type_definitions": [...]
    },
  ],
  "continuation_token": "eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ=="
}

Provide a way of distinguishing between user types

We don't have a good way to distinguish between different user types (user:x, group:x#member, and user:*) in a strongly typed way and so in ListObjects we are forced to do this:

https://github.com/openfga/openfga/blob/e9bd83df3f61550d1704e14abbb47a2474cb8abf/pkg/server/commands/connected_objects.go#L30C1-L83

upgrade to buf/protovalidate

protoc-gen-validate is superseded in the community by the official buf/protovalidate package. The protovalidate package brings some nice additions that we should make use of. Namely, we can control the error message explicitly, and so this improves our API DX with error messages returned from the protobuf validation middleware layer.

See:

• https://buf.build/blog/protoc-gen-validate-v1-and-v2/
• https://github.com/bufbuild/protovalidate/tree/main

refactor: change TypeDefinition signature to be more canonical

Today a TypeDefinition has the following protobuf definition:

message TypeDefinition {
    string type = 1;
    map<string, Userset> relations = 2;
    Metadata metadata = 3;
}

https://github.com/openfga/api/blob/main/openfga/v1/authzmodel.proto#L26

A more canonical and easier consume definition of a TypeDefinition would look like:

message TypeDefinition {
    string type = 1;
    map<string, Relation> relations = 2;
}

https://github.com/openfga/api/blob/main/openfga/v1/authzmodel.proto#L42

The only reason(s) why the metadata field is needed today is because we did not want to break existing compatibility with the Userset definition in the map<string, Userset> and so we introduced an additional field. The Relation definition itself should encapsulate all of the information/metadata associated with the relation. Doing so will allow the OpenFGA core and other integrations to more seemlessly make use of a TypeDefinition and the relations contained therein without having to reconstruct a map[string]Relation all over the place in client code.

References:
https://github.com/openfga/openfga/pull/726/files#r1189164147

Make required fields required

This includes:

• In WriteAuthorizationModelRequest, schema_version should be required
• In ReadAuthorizationModelRequest, id should be required
• In TupleKey all are required
• All responses

These currently cause a lot of DX problems in the SDKs, as the generated types show that the fields are optional.

E.g. In the typescript SDK, users have to check for nullability on responses even if we know it will never be null, and they mistakenly think that some fields are optional in requests even when they are.

In the Go SDK, we have to make the fields accept pointer instead of values because of this when it is unnecessary

ListObjects: Does not specify response format

The response should show an example where the returned strings are in object format <type>:<id>

Inconsistent description for read

The description for READ suggests that you can specify authorization model id. However, the actual protobuf / model description suggests that you cannot specify this.

Breaking Change in Proto Field Ordering

This proto field re-ordering breaks compatibility. The user and object fields get swapped, and tuple checks are just entirely misinterpreted:
5daf658#diff-2a88655b667aad16ec564eded7b5739e88e7d8b9da8a5231008519c3d3b80bb9L28

PR here: #97

It looks like assertions were similarly affected and that change was reverted. Was there some kind of safe, backwards compatible migration that I missed? I would have assumed more people would be affected by this breaking change.

Add buf format validation to CI

In .github/workflows/pull_request.yaml something like the following should work:

name: Pull Request

on:
  pull_request:
    branches:
      - main

jobs:
  buf-fmt:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - uses: bufbuild/buf-setup-action@v1
        with:
          version: '1.4.0'

      - run: buf format -d --exit-code

Regex check is overzaelous

See b7cfc0c#r77087138

update read API description

Read API description should change from

Query for all users with particular relationships for a particular document

to

Query for all stored relationship tuples that have a particular relation and object