Added

• Bounded concurrency limiter for Check and ListObjects queries (#860, #887)

  New server configurations can be provided to limit/bound the amount of concurrency that is allowed during query evaluation. These settings can help reduce the impact/burden that a single query (e.g. Check, ListObjects, etc..) can have on the underlying database and OpenFGA server.

  • --maxConcurrentReadsForListObjects - The maximum allowed number of concurrent reads in a single ListObjects query.

  • --maxConcurrentReadsForCheck - The maximum allowed number of concurrent reads in a single Check query.

  • --resolveNodeBreadthLimit - Defines how many nodes on a given level can be evaluated concurrently in a Check resolution tree.

• Jaeger persistent storage for traces in docker-compose.yaml (#888) - thanks @Azanul

Fixed

• Disable default debug level-logging in retryablehttp client (#882) - thanks @KlausVii

Changed

• [BREAKING] Imports for OpenFGA protobuf API dependencies (#898)

  • Problem - Previously we depended on Buf remote generated packages, but they recently deprecated protobuf imports served from the go.buf.build domain (see Migrate from remote generation alpha). OpenFGA builds are currently broken as a result of this.

  • Change - We switched our protobuf API dependency from go.buf.build/openfga/go/openfga/api/openfga/v1 to github.com/openfga/api/proto/openfga/v1. So we no longer use Buf remote generated packages in favor of packages we manage in the openfga/api repository. This fixes existing build issues.

  • Impact - Developers using the OpenFGA as a library or the gRPC API must change their protobuf dependency from go.buf.build/openfga/go/openfga/api/openfga/v1 to github.com/openfga/api/proto/openfga/v1. A global find/replace and package depedency update should fix it. Here's a diff demonstrating the changes for a Go app, for example:

    import (
      ...
    - openfgav1 "go.buf.build/openfga/go/openfga/api/openfga/v1"
    + openfgav1 "github.com/openfga/api/proto/openfga/v1"
    )
    

• Refactor the Server constructor to use the options builder pattern (#833)

  import (
    openfga "github.com/openfga/openfga/pkg/server"
  )
  
  s := openfga.New(
    &server.Dependencies{...},
    &server.Config{...},
  )
  

  becomes

  import (
    openfga "github.com/openfga/openfga/pkg/server"
  )
  
  var opts []openfga.OpenFGAServiceV1Option
  s := openfga.MustNewServerWithOpts(opts...)
  

Added

• Optimizations for ListObjects and StreamedListObjects for models involving intersection (and) and exclusion (but not) (#797)

Changed

• Cache model validation results on first model load (#831)
• Cache inflight requests when looking up any authorization model (#831)
• Update postgres max connections in docker compose file (#829)

This is the third release candidate that improves ListObjects performance for models involving intersection and/or exclusion (and or but not). (https://github.com/openfga/openfga/pull/797). The changes herein include the security patch fix that was introduced for CVE-2023-35933, so if you're using v1.2.0-rc1 or v1.2.0-rc2, then please upgrade.

To test out the new experimental support for optimized ListObjects you can run OpenFGA with --experimentals optimized-list-objects. A docker image of this release candidate is available openfga/openfga:v1.2.0-rc3.

Added

• Official Homebrew installation instructions (#781) - thanks @chenrui333
• The --verbose flag has been added to the openfga migrate command (#776)
• The openfga validate-models CLI command has been introduced to validate all models across all stores (#817)

Changed

• Updated the version of the grpc-health-probe binary included in OpenFGA builds (#784)
• Cache inflight requests when looking up the latest authorization model (#820)

Fixed

• Validation of models with non-zero entrypoints (#802)
• Remove unintended newlines in model validation error messages (#816) - thanks @Galzzly

Security

• Patches CVE-2023-35933 - additional model validations are now applied to models that can lead to the vulnerability. See the CVE report for more details, and don't hesitate to reach out if you have questions.

This is the second release candidate that improves ListObjects performance for models involving intersection and/or exclusion (and or but not). (https://github.com/openfga/openfga/pull/797)

To test out the new experimental support for optimized ListObjects you can run OpenFGA with --experimentals optimized-list-objects. A docker image of this release candidate is available openfga/openfga:v1.2.0-rc2.

Changed

• Concurrently evaluate objects that require further evaluation instead of serially.

Added

• optimized-list-objects experimental flag to improve ListObjects performance for models involving intersection and/or exclusion (and or but not). (#797)

  To test out the new experimental support for optimized ListObjects you can run OpenFGA with --experimentals optimized-list-objects. A docker image of this release candidate is available openfga/openfga:v1.2.0-rc1.

Full changelog

Added

• Streaming ListObjects has no limit in number of results returned (#733)

Fixed

• Avoid DB connection churning in unoptimized ListObjects (#711)
• Ensure ListObjects respects configurable ListObjectsDeadline (#704)
• In Write, throw 400 instead of 500 error if auth model ID not found (#725)
• Performance improvements when loading the authorization model (#726)
• Ensure Check evaluates deterministically on the eval boundary case (#732)

Changed

• [BREAKING] The flags to turn on writing and evaluation of v1.0 models have been dropped (#763)

Fixed

• Correct permission and location for gRPC health probe in Docker image (#697)

Ready for Production with Postgres

OpenFGA with Postgres is now considered stable and ready for production usage.

Fixed

• MySQL migration script errors during downgrade (#664)

Added

• Release artifacts are now signed and include a Software Bill of Materials (SBOM) (#683)

  The SBOM (Software Bill of Materials) is included in each Github release using Syft and is exported in SPDX format.

  Developers will be able to verify the signature of the release artifacts with the following workflow(s):

  wget https://github.com/openfga/openfga/releases/download/<tag>/checksums.txt
  
  cosign verify-blob \
    --certificate-identity 'https://github.com/openfga/openfga/.github/workflows/release.yml@refs/tags/<tag>' \
    --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
    --cert https://github.com/openfga/openfga/releases/download/<tag>/checksums.txt.pem \
    --signature https://github.com/openfga/openfga/releases/download/<tag>/checksums.txt.sig \
    ./checksums.txt
  

  If the checksums.txt validation succeeds, it means the checksums included in the release were not tampered with, so we can use it to verify the hashes of other files using the sha256sum utility. You can then download any file you want from the release, and verify it with, for example:

  wget https://github.com/openfga/openfga/releases/download/<tag>/openfga_<version>_linux_amd64.tar.gz.sbom
  wget https://github.com/openfga/openfga/releases/download/<tag>/openfga_<version>_linux_amd64.tar.gz
  
  sha256sum --ignore-missing -c checksums.txt
  

  And both should say "OK".

  You can then inspect the .sbom file to see the entire dependency tree of the binary.

  Developers can also verify the Docker image signature. Cosign actually embeds the signature in the image manifest, so we only need the public key used to sign it in order to verify its authenticity:

  cosign verify -key cosign.pub openfga/openfga:<tag>
  

• openfga migrate now accepts reading configuration from a config file and environment variables like the openfga run command (#655) - thanks @suttod!

• The --trace-service-name command-line flag has been added to allow for customizing the service name in traces (#652) - thanks @jmiettinen

Fixed

• Postgres and MySQL implementations have been fixed to avoid ordering relationship tuple queries by ulid when it is not needed. This can improve read query performance on larger OpenFGA stores (#677)
• Synchronize concurrent access to in-memory storage iterators (#587)
• Improve error logging in the openfga migrate command (#663)
• Fix middleware ordering so that requestid middleware is registered earlier(#662)

Changed

• Bumped up to Go version 1.20 (#664)

• Default model schema versions to 1.1 (#669)

  In preparation for sunsetting support for models with schema version 1.0, the WriteAuthorizationModel API will now interpret any model provided to it as a 1.1 model if the schema_version field is omitted in the request. This shouldn't affect default behavior since 1.0 model support is enabled by default.

Fixed

• Correct migration path for mysql in openfga migrate (openfga/openfga#644)

v0.4.1

The v0.4.1 release includes everything in v0.4.0 which includes breaking changes. The v0.4.0 release was held due to an issue discovered after the release was cut.

Fixed

• Fix ListObjects not returning objects a user has access to in some cases (openfga/openfga#637)

v0.4.0

Removed

• [BREAKING] Disable schema 1.0 support, except if appropriate flags are set (openfga/openfga#613)
  • As of this release, OpenFGA no longer allows writing or evaluating schema v1.0 models by default. If you need support for it for now, you can use the:
    • OPENFGA_ALLOW_WRITING_1_0_MODELS: set to true to allow WriteAuthorizationModel to accept schema v1.0 models.
    • OPENFGA_ALLOW_EVALUATING_1_0_MODELS: set to true to allow Check, Expand, ListObjects, Write and WriteAssertions that target schema v1.0 models.
    • ReadAuthorizationModel, ReadAuthorizationModels and ReadAssertions are unaffected and will continue to work regardless of the target model schema version.
  • Note that these flags will be removed and support fully dropped in a future release. Read the Schema v1.0 Deprecation Timeline for more details.

Added

• Add OpenFGA version command to the CLI (openfga/openfga#625)
• Add timeout flag to migrate command (openfga/openfga#634)

Fixed

• Improve the speed of Check for 1.1 models by using type restrictions (openfga/openfga#545, openfga/openfga#596)
• Various important fixes to the experimental ListObjects endpoint
  • Improve readUsersets query by dropping unnecessary sorting (openfga/openfga#631, openfga/openfga#633)
  • Fix null pointer exception if computed userset does not exist (openfga/openfga#572)
  • Fix race condition in memory store (openfga/openfga#585)
  • Ensure no objects returned that would not have been allowed in Checks (openfga/openfga#577)
  • Reverse expansion with indirect computed userset relationship (openfga/openfga#611)
  • Improved tests (openfga/openfga#582, openfga/openfga#599, openfga/openfga#601, openfga/openfga#620)
• Tuning of OTEL parameters (openfga/openfga#570)
• Fix tracing in Check API (openfga/openfga#627)
• Use chainguard images in Dockerfile (openfga/openfga#628)

Added

• OpenFGA Playground support (#68)
• CORS policy configuration (#65)

Fixed

• Contextual tuple propagation in the un-optimized ListObjects implementation (fixes openfga/openfga#557)

Re-release of v0.3.5 because the go module proxy cached a prior commit of the v0.3.5 tag.

Added

• grpc-health-probe for Health Checks (#520)

  OpenFGA containers now include an embedded grpc_health_probe binary that can be used to probe the Health Check endpoints of OpenFGA servers. Take a look at the docker-compose.yaml file for an example.

• Improvements to telemetry: logging, tracing, and metrics (#468, #514, #517, #522)

  • We have added Prometheus as the standard metrics provided for OpenFGA and provide a way to launch Grafana to view the metrics locally. See docker-compose.yaml for more information.

  • We've improved the attributes of various trace spans and made sure that trace span names align with the functions they decorate.

  • Our logging has been enhanced with more logged fields including request level logging which includes a request_id and store_id field in the log message.

  These features will allow operators of OpenFGA to improve their monitoring and observability processes.

• Nightly releases (#508) - thanks @Siddhant-K-code!

  You should now be able to run nightly releases of OpenFGA using docker pull openfga/openfga:nightly

Fixed

• Undefined computed relations on tuplesets now behave properly (#532)

  If you had a model involing two different computed relations on the same tupleset, then it's possible you may have received an internal server error if one of the computed relations was undefined. For example,

  type document
    relations
      define parent as self
      define viewer as x from parent or y from parent
  
  type folder
    relations
      define x as self
  
  type org
    relations
      define y as self
  

  Given the tuple { user: "org:contoso", relation: "parent", object: "document:1" }, then Check({ user: "jon", relation: "viewer", object: "document:1" }) would return an error prior to this fix because the x computed relation on the document#parent tupleset relation is not defined for the org object type.

• Eliminate duplicate objects in ListObjects response (#528)

Fixed

• Fixed the environment variable mapping (#498). For the full list of environment variables see .config-schema.json.
• Fix for stack overflow error in ListObjects (#506). Thank you for reporting the issue @wonderbeyond!

Added

• Added OpenTelemetry tracing (#499)

Removed

• The ReadTuples endpoint has been removed (#495). Please use Read with no tuple key instead (e.g. POST /stores/<store_id>/read with {} as the body).

Added

• Environment variable names have been updated (#472).

  For example, OPENFGA_MAX_TUPLES_PER_WRITE instead of OPENFGA_MAXTUPLESPERWRITE.

  For the full list please see .config-schema.json.

  The old form still works but is considered deprecated and should not be used anymore.

• Optimized ListObjects is now on by default (#489) (--experimentals="list-objects-optimized" is no longer needed)

• Avoid connection churn in our datastore implementations (#474)

• The default values for OPENFGA_DATASTORE_MAX_OPEN_CONNS and OPENFGA_DATASTORE_MAX_IDLE_CONNS have been set to 30 and 10 respectively (#492)

Fixed

• ListObjects should no longer return duplicates (#475)

Added

• OpenTelemetry metrics integration with an otlp exporter (#360) - thanks @AlexandreBrg!

  To export OpenTelemetry metrics from an OpenFGA instance you can now provide the otel-metrics experimental flag along with the --otel-telemetry-endpoint and --otel-telemetry-protocol flags. For example,

  ./openfga run --experimentals=otel-metrics --otel-telemetry-endpoint=127.0.0.1:4317 --otel-telemetry-protocol=http
  

  For more information see the official documentation on Experimental Features and Telemetry.

• Type-bound public access support in the optimized ListObjects implementation (when the list-objects-optimized experimental feature is enabled) (#444)

Fixed

• Tuple validations for models with schema version 1.1 (#446, #457)
• Evaluate rewrites on nested usersets in the optimized ListObjects implementation (#432)

Added

• Datastore configuration flags to control connection pool settings
  --datastore-max-open-conns
--datastore-max-idle-conns
--datastore-conn-max-idle-time
--datastore-conn-max-lifetime
  These flags can be used to fine-tune database connections for your specific deployment of OpenFGA.

• Log level configuration flags
  --log-level (can be one of ['none', 'debug', 'info', 'warn', 'error', 'panic', 'fatal'])

• Support for Experimental Feature flags
  A new flag --experimentals has been added to enable certain experimental features in OpenFGA. For more information see Experimental Features.

Security

• Patches CVE-2022-23542 - relationship reads now respect type restrictions from prior models [openfga/openfga#422]