Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Try to keep listed changes to a concise bulleted list of simple explanations of changes. Aim for the amount of information needed so that readers can understand where they would look in the codebase to investigate the changes' implementation, or where they would look in the documentation to understand how to make use of the change in practice - better yet, link directly to the docs and provide detailed information there. Only elaborate if doing so is required to avoid breaking changes or experimental features from ruining someone's day.

Unreleased

Added

Documenting OpenFGA release process #1923
Cache Controller to extend Sub-problems and Iterators lifetime in cache #2006

Fixed

Label ListUsers API calls #2000

1.6.2 - 2024-10-03

Added

Improve tracing in Check API by enhancing discoverability of model ID. #1964
Improve tracing in all APIs by adding the store ID to the span. #1965
Add a cache for datastore iterators on Check API. #1924.

Can be configured via OPENFGA_CHECK_ITERATOR_CACHE_ENABLED and OPENFGA_CHECK_ITERATOR_CACHE_MAX_RESULTS.

Changed

ReadChanges now supports sorting. #1976.

This is a breaking change related to the storage interface. If you are not implementing a storage adaptor, then these changes should not impact you.

Removed

Removed deprecated opentelemetry-connector memory_ballast extension. #1942.
Removed experimental logging of cache hits for each subproblem in Check API calls. #1960.

Fixed

Handle all permutations of SQLite busy / locked errors #1936. Thanks @DanCech!
Goroutine leak in Check API introduced in v1.6.1 #1962.
Broken migration from v.1.4.3 to v1.5.4 (openfga#1668) #1980 and #1986.
Upgrade go from 1.22.6 to 1.22.7 to address CVE-2024-34156 #1987. Thanks @golanglemonade!

Performance

Improve check performance in the case that the query involves resolving nested userset. Enable via experimental flag enable-check-optimizations. #1945

1.6.1 - 2024-09-12

Changed

Support context in assertions #1907

Added

Support for graceful shutdown on SIGTERM signal, improving termination handling in containerized environments #1928. Thanks @flex-seongbok @Siddhant-K-code
Stack trace when logging panics #1904
Throttling metric throttled_requests_count for observing the number of throttled requests for a given throttling configuration #1863
New metric on number of allowed vs. non-allowed Check responses #1911

New datastore engine: SQLite (beta) #1615

openfga migrate --datastore-engine sqlite --datastore-uri openfga.sqlite
openfga run --datastore-engine sqlite --datastore-uri openfga.sqlite

Thanks @DanCech!

Fixed

When a request gets cancelled by a client, throw a 4xx, not a 5xx. #1905
Makes the pkg.logger.Logger.With immutable by creating a child logger instead of mutating the delegate one to prevent side effects 1906
Extend request timeout to 10s for slow tests 1926

Performance

Improve performance of Check API in the case that the query involves resolving a tuple to userset and/or a userset, by streaming intermediate results. #1888

1.6.0 - 2024-08-30

Changed

Consistency options experimental flag has been removed and is now enabled by default. Refer to the consistency options documentation for details. #1889
Require at least Go 1.22.6 #1831. Thanks @tranngoclam
Add a "query_duration_ms" field on each log #1807. Thanks @lalalalatt
Default logging to stdout instead of stderr #1830

Fixed

Check API: internal fixes #1843
Correct docker file syntax #1852

Performance

Performance improvements for Check API:
- introduce an optimization when the input request relation is pointing to a computed relation #1793
- batch calls that compute membership checks and start processing them earlier #1804
- performance improvement in wildcard scenarios #1848
Performance improvement in tuple validation on reads #1825

Breaking changes

Set a maximum limit on bytes to the WriteAssertions API: 64 KB #1847

1.5.9 - 2024-08-13

Security

Address CVE-2024-42473 - a critical issue where Check API can return incorrect responses. Please see the CVE report for more details.

1.5.8 - 2024-08-07

Added

Performance improvements for Check API:
- introduce an optimization when the input request relation is pointing to a computed relation #1793
- batch calls that compute membership checks and start processing them earlier #1804
Logging number of cache hits for each subproblem of each authorization model for Check API calls. Enabled with the OPENFGA_CHECK_TRACKER_ENABLED flag. #1785
Aliases for issuers and subject validation in OIDC AuthN mode using OPENFGA_AUTHN_OIDC_ISSUER_ALIASES and OPENFGA_AUTHN_OIDC_SUBJECTS respectively #1784 Thanks @Code2Life!
Dispatch Throttling for our ListUsers API. This can be enabled using OPENFGA_LIST_USERS_DISPATCH_THROTTLING_ENABLED and the env variables below. #1658
- OPENFGA_LIST_USERS_DISPATCH_THROTTLING_THRESHOLD - The number of dispatches allowed before throttling is triggered
- OPENFGA_LIST_USERS_DISPATCH_THROTTLING_MAX_THRESHOLD - The maximum number of dispatches allowed before the request is rejected
- OPENFGA_LIST_USERS_DISPATCH_THROTTLING_FREQUENCY - The frequency at which the deprioritized throttling queue is processed
Support sending contextual tuples in the Write Assertions API. #1821

Fixed

address "expected exactly one terminal relation for fast path, received {num}" error during Check for models with type restrictions with and without a condition or with multiple conditions. #1814

1.5.7 - 2024-07-25

Added

Support requesting a different consistency option per request in Check, Expand, ListObjects, ListUsers, and Read #1764
- This is currently experimental and needs to be enabled by configuring OPENFGA_EXPERIMENTALS=enable-consistency-params or passing --experimentals enable-consistency-params to openfga run.
- When HIGHER_CONSISTENCY is requested, OpenFGA will skip the check resolver cache. For storage implementors it is recommended to skip any caching and perform a stronger read if HIGHER_CONSISTENCY is requested. This can be accessed in the Consistency options provided to the relevant methods of the storage interface.
Start publishing images to ghcr.io/openfga/openfga as alternative to DockerHub #1775 - Thanks @JAORMX!
Performance improvements for parent child relations in Check #1765
Performance improvement in Check: computed relations don't consume from the resolution depth quota, don't trigger additional goroutines, and don't get cached #1786

Changed

Update to Go 1.22 in container image #1776 - Thanks @tranngoclam!

Breaking Changes ⚠️

Note

The following breaking changes are related to the storage interface. If you are not implementing a storage adaptor, then there are these changes should not impact your usage of OpenFGA.

Removal of `PaginationOptions` in favour of a per-method `Options` type #1732

The options parameter of type PaginationOptions has been replaced with a per-method type that contains a Pagination field that contains this data in the following methods:

ReadAuthorizationModels - Type is ReadAuthorizationModelsOptions
ListStores - Type is ListStoresOptions
ReadChanges - Type is ReadChangesOptions
ReadPage - Type is ReadPageOptions

Introduction of new `Options` types to certain methods in the storage interface to facilitate consistency data #1750

The following methods have had an options parameter introduced to the method signature to include consistency data, or the existing options parameter has been expanded to hold consistency data.

This consistency data should be used to help determine whether any form of caching should be used as part of the read performed by the storage adapter.

Read - Added a new parameter of type ReadOptions
ReadPage - Added Consistency to existing ReadPageOptions type
ReadUserSetTuples - Added a new parameter of type ReadUserSetTuplesOptions
ReadStartingWithUser - Added a new parameter of type ReadStartingWithUserOptions

1.5.6 - 2024-07-17

Added

Performance improvements to userset subproblem resolutions in Check in certain scenarios #1734
Performance improvements to tuple-to-userset subproblem resolutions in Check in certain scenarios #1735
Warning when log level set to none #1705 - thank you, @Siddhant-K-code!
Minor performance improvement for queries when model ID not specified #1754

Fixed

Race condition in ListUsers which could erroneously swallow errors #1755
"relation is undefined" error in Check and ListUsers #1767
Request ID included with Streaming ListObjects responses #1636

Removed

ListUsers experimental flag (will continue to work if passed) #1730

1.5.5 - 2024-06-18

Added

Configuring maximum cost for CEL evaluation via OPENFGA_MAX_CONDITION_EVALUATION_COST #1631 - thank you, @cmmoran

Fixed

OTel trace context propagation to grpc-gateway #1624 - thank you, @Zach-Johnson

Removed

excluded_users from ListUsers response. Further discovery required before being reintroduced. If impacted by this removal, please provide feedback in issue #1692 #1685

1.5.4 - 2024-05-29

Added

ListUsers API which answers the question "what users are related to a specific object?". This feature is experimental and can be enabled by configuring OPENFGA_EXPERIMENTALS=enable-list-users. Also see Performing a ListUsers call and ListUsers API docs. Known Limitation: Child usersets that are negated from their parent are currently not returned as excluded_users #1433
ListObjects throttling to manage resource usage of expensive queries. Throttling improves overall query performance by limiting the number of dispatches, which are the recursive sub-operations of a ListObjects query #1571
Per-request dispatch throttling threshold configuration via context #1546
Self-defining usersets for Check, ListObjects and ListUsers. These are implicit tuples that exist by virtue of set theory. For example, the userset document:1#viewer implicitly possess the viewer relation for document:1 #1521
Panic recovery handling for all APIs #1557
Logging of non-sensitive server configuration on startup #1609
Appropriate error codes for throttled requests indicating if a request should be retried #1552
Minor performance improvements in Check API by reducing quantity of spans created #1550, #1589

Fixed

Goroutine leak occurring during initial server validation #1617
Stricter filtering of invalid tuples with ListObjects #1563
Panic on server close if caching is enabled #1568
Prevent calling datastore if context has error #1593

Changed

request_id is now same as trace_id (e.g. 1e20da43269fe07e3d2ac018c0aad2d1) if tracing is enabled. Otherwise, remains an UUID (e.g. 38fee7ac-4bfe-4cf6-baa2-8b5ec296b485) #1576 - thank you, @00chorch

Removed

request_duration_by_query_count_ms metric #1579

1.5.3 - 2024-04-16

Added

Apply tags to requests that have been intentionally throttled (openfga#1531). This will add a new log field titled "throttled" to such requests.

Fixed

Panic that occurred on Check API with some authorization models and tuples (openfga#1517)

Changed

Modular Models (Schema 1.2) support is enabled by default and the experimental flag for it has been dropped (openfga#1520)
Bumped to Go 1.21.9 (openfga#1523)

Security

Patch CVE-2024-31452 - a critical issue where Check and ListObjects APIs returns incorrect results for some models and tuples. See the CVE report for more details.

1.5.2 - 2024-04-03

Fixed

Fix the count of datastore reads in the Check API (#1452)
Fix the correct default used for dispatch throttling (#1479)

Security

Bumped up the grpc-health-probe dependency in the published Docker image to the latest release which fixes some vulnerabilities (#1507)

Contributions

Add homebrew release job by @chenrui333 (#780)

1.5.1 - 2024-03-19

Added

Include calls to ListObjects and StreamedListObjects methods in the dispatch_count histogram (#1427)
Added request_duration_ms histogram which has datastore_query_count and dispatch_count as dimensions (#1444)
Added new flag OPENFGA_AUTHN_OIDC_ISSUER_ALIASES to specify oidc issuer aliases (#1354) - Thanks @le-yams!
Added experimental support for modular models via OPENFGA_EXPERIMENTALS=enable-modular-models (#1443). This will enable writing models that are split across multiple files.
Added support for throttling dispatches (#1440). This will throttle Check requests that are overly complex. You can turn on this feature via OPENFGA_DISPATCH_THROTTLING_ENABLED and configured via OPENFGA_DISPATCH_THROTTLING_THRESHOLD and OPENFGA_DISPATCH_THROTTLING_FREQUENCY

Fixed

Throw HTTP 400 when tuple condition is invalid instead of HTTP 500 (#1420)
Fix model validation which threw error "no entrypoints defined" (#1422)

Deprecation ⚠️

Histogram request_duration_by_query_count_ms will be removed in the next release, in favour of request_duration_ms (#1450)

Contribution

Thanks @lekaf974 for enhancing NewLogger with builder pattern options (#1413)

1.5.0 - 2024-03-01

Added

Override option for timestamp in JSON logs (#1330) - thank you, @raj-saxena!
OpenTelemetry tracing and attributes to check algorithm (#1331, #1388)
Dispatch count to check response metadata as a query complexity heuristic (#1343)

Fixed

Cycles detected during check now deterministically return with {allowed:false} (#1371, #1372)
Fix incorrect path for gPRC health check (#1321)

Breaking Change ⚠️

The AuthorizationModelReadBackend interface method FindLatestAuthorizationModelID has changed to FindLatestAuthorizationModel for performance improvements. #1387

If you implement your own data store, you will need to make the following change:

Before

After

func (...) FindLatestAuthorizationModelID(ctx context.Context, storeID string) (string, error) {
  //...get model ID
  return modelID, nil
}

func (...) FindLatestAuthorizationModel(ctx context.Context, storeID string) (*openfgav1.AuthorizationModel, error) {
  //...get model
  return model.(*openfgav1.AuthorizationModel), nil
}

1.4.3 - 2024-01-26

Added

Add ability to close all server resources through server.Stop() (#1318)

Changed

Increase performance by removing redundant map.Clone() calls in model validation (#1281)

Fixed

Fix the sorting of contextual tuples when generating a cache key during check (#1299)

Security

Patch CVE-2024-23820 - a critical issue where issuing many ListObjects API calls that hit the --listObjects-deadline setting can lead to an out of memory error. See the CVE report for more details

1.4.2 - 2024-01-10

Fixed

Goroutine leak in ListObjects because of a leak in ReverseExpand (#1297)

1.4.1 - 2024-01-04

Changed

Reduce goroutine overhead in ListObjects (#1173)
Added openfga prefix to custom exported Prometheus metrics

⚠️ This change may impact existing deployments of OpenFGA if you're integrating with the metrics reported by OpenFGA.

Custom metrics reported by the OpenFGA server are now prefixed with openfga_. For example, request_duration_by_query_count_ms is now exported as openfga_request_duration_by_query_count_ms.

Added

Support for cancellation/timeouts when evaluating Conditions (#1237)
Tracing span info for Condition evaluation (#1251)

Fixed

1.4.0 - 2023-12-11

Changed

Enable support for Conditional Relationship Tuples by default. (#1220)
Added stricter gRPC server max message size constraints (#1222)

We changed the default gRPC max message size (4MB) to a stricter 512KB to protect the server from excessively large request context fields. This shouldn't impact existing clients since our calculated max message size should be much smaller than 512KB given our other input constraints.

1.3.10 - 2023-12-08

Changed

Bumped up to Go 1.21.5 (#1219)

Fixed

Reorder protobuf fields for persisted Assertions (#1217)

Assertions written on or after v1.3.8 should be re-written to resolve some binary encoding issues that were introduced.
Handle floating point conversion errors in conditions (#1200)

1.3.9 - 2023-12-05

Fixed

Avoid panic when processing a nil set of writes (#1208) - thanks @stgraber!
Decoding of null conditions in SQL storage implementations (#1212)

1.3.8 - 2023-12-04

Added

Experimental support for ABAC Conditional Relationships.

To enable experimental support for ABAC Conditional Relationships you can pass the enable-conditions experimental flag. For example, openfga run --experimentals=enable-conditions. The upcoming v1.4.0 release will introduce official support for this new feature. For more information please see our official blog post. The v1.4.0 release will have more official documentation on openfga.dev.

⚠️ If you enable experimental support for ABAC and introduce models and/or relationship tuples into the system and then choose to rollback to a prior release, then you may experience unintended side-effects. Care should be taken!

Read on for more information.

If you introduce a model with a condition defined in a relation's type restriction(s) and then rollback to a prior OpenFGA release, then the model will be treated as though the conditioned type restriction did not exist.
```
model
  schema 1.1

type user

type document
  relations
    define viewer: [user with somecondition]

condition somecondition(x: int) {
  x < 100
}
```
and then you rollback to v1.3.7 or earlier, then the model above will be treated equivalently to
```
model
  schema 1.1

type user

type document
  relations
    define viewer: [user]
```
Likewise, if you write a relationship tuple with a condition and then rollback to a prior release, then the tuple will be treated as an unconditioned tuple.
```
- document:1#viewer@user:jon, {condition: "somecondition"}
```
will be treated equivalently to document:1#viewer@user:jon in v1.3.7 or earlier. That is, Check(document:1#viewer@user:jon) would return {allowed: true} even though at the tuple was introduced it was conditioned.
Minimum datastore schema revision check in the server's health check (#1166)

Each OpenFGA release from here forward will explicitly reference a minimum datastore schema version that is required to run that specific release of OpenFGA. If OpenFGA operators have not migrated up to that revision then the server's health checks will fail.
Username/password configuration overrides for the openfga migrate entrypoint (#1133). Thanks for the contribution @martin31821!

Similar to the server's main entrypoint openfga run, you can now override the datastore username and password with environment variables. when running the openfga migrate utility.
Healthcheck definitions in Dockerfile (#1134). Thanks @Siddhant-K-code!

Changed

Database iterators yielded by the RelationshipTupleReader storage interface now accept a context parameter which allows iteration to be promptly terminated (#1055)

We have noticed improvements in query performance by adding this because once a resolution path has been found we more quickly cancel any further evaluation by terminating the iterators promptly.
Improved tuple validation peformance with precomputation of TTUs (#1171)
Refactored the commands in the pkg/server/commands package to uniformly use the Options builder pattern (#1142). Thanks for the contribution @ilaleksin!
Upgraded to Go 1.21.4 (#1143). Thanks @tranngoclam!

Fixed

If two requests were made with the same request body and contextual tuples but the order of the contextual tuples differed, then the cache key that is produced is now the same.(#1187)
Use NoOp TracerProvider if tracing is disabled (#1139 and #1196)

1.3.7 - 2023-11-06

Security

Bumped up the grpc-health-probe dependency to the latest release which fixed some vulnerabilities.

1.3.6 - 2023-11-06

Added

Provenance manifests generation (`openfga.intoto.jsonl``) for verification of release artifacts with SLSA attestations.

Changed

Removed the experimental flag check-query-cache. If you wish to enable the Check query cache you no longer need the experimental flag.

1.3.5 - 2023-10-27

Added

Export metrics from MySQL and Postgres (#1023)

To export datastore metrics, set OPENFGA_METRICS_ENABLED=true and OPENFGA_DATASTORE_METRICS_ENABLED=true.

Fixed

Changed

Write Authorization Models in a single database row (#1030)

⚠️ In order to avoid downtime, we recommend upgrading to at least v1.3.3 before upgrading to v1.3.5.

This is the second of a series of releases that will progressively introduce changes via code and database migrations that will allow authorization models to be stored in a single database row.

See here for more details.

1.3.4 - 2023-10-17

Fixed

Incorrect string in model validation error message (#1057)
Incorrect results can be returned by Check API when passing in contextual tuples and the check-query-cache experimental flag is turned on (#1059)

Changed

Bumped up to Go 1.21.3 (#1060)

Security

Patches CVE-2023-45810. See the CVE for more details

1.3.3 - 2023-10-04

Full changelog

Added

Configurable size limit for Authorization Models (#1032)

We've introduced a new size limit for authorization models, provided a consistent behavior across datastores, which defaults to 256KB. This can be configured by using the --max-authorization-model-size-in-bytes flag.

Fixed

Reduce use of GOB in encoded cache key (#1029)

Changed

Move standalone server config defaults (#1036)
Persist Authorization Models serialized protobuf in the database (#1028)

In the next series of releases will progressively introduce changes via code and database migrations that will allow authorization models to be stored in a single database row.

See here for more details.

1.3.2 - 2023-08-25

Added

Support TLS for OTLP trace endpoint (#885) - thanks @matoous
Configurable limits to database reads per ListObjects query (#967)
Datastore query count labels to traces and query latency histogram in ListObjects (#959)
GitHub workflow to check Markdown links (#1016) - thanks @sanketrai1

Fixed

Change response code to internal error for concurrency conflicts (#1011)

Changed

Use slices and maps packages from go1.21 (#969) - thanks @tranngoclam
Moved request validations to RPC handlers so library integrations benefit (#975, #998)
Refactored internal usages of ConnectedObjects to ReverseExpand (#968)
Expose validation middleware (#1005)
Upgrade grpc validator middleware to the latest v2 package (#1019) - thanks @tranngoclam

Security

Patches CVE-2023-43645 - see the CVE for more details

[BREAKING] If your model contained cycles or a relation definition that has the relation itself in its evaluation path, then Checks and queries that require evaluation will no longer be evaluated on v1.3.2+ and will return errors instead. You will need to update your models to remove the cycles.

1.3.1 - 2023-08-23

Added

Count datastore queries involved in Check resolution metadata (#880)

OpenFGA request logs and traces will now include a field datastore_query_count that shows how many queries were involved in a single Check resolution.
Histogram metric to report the datastore_query_count per Check (#924)

This new metric can be used to report percentiles of the number of database queries required to resolve Check requests.
Check request duration histogram labeled by method and datastore query count (#950)

The request_duration_by_query_count_ms metric reports the total request duration (in ms) labelled by the RPC method and ranges of observations for the datastore_query_count. This metrics allows operators of an OpenFGA server to report request duration percentiles for Check requests based on the number of database queries that were required to resolve the query.
Optimize Check to avoid database lookups in some scenarios (#932)
CachedCheckResolver for caching Check subproblems (#891)

This experimental feature adds new caching capabilities to the OpenFGA server. It is an "opt-in" feature and thus must be enabled. To enable this feature you must specify the experimental flag check-query-cache and set the --check-query-cache-enabled=true flag.
```
openfga run --experimentals check-query-cache --check-query-cache-enabled=true
```
Server request logs now include the user-agent (#943)

Changed

Default Check and ListObjects concurrency read limits (#916)

In our last release v1.3.0 we modified the default behavior of Check and ListObjects such that it limits/restricts the degree of concurrency that is allowed for a single request. This change was unintended. This release reverts the default behavior back to unbounded concurrency limits (the prior default). The change mostly affects those using OpenFGA as a library.
Bumped up to Go 1.21 (#952)

Security

Patches CVE-2023-40579 - see the CVE for more details

1.3.0 - 2023-08-01

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 managed 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 dependency 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...)

1.2.0 - 2023-06-30

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)

1.1.1 - 2023-06-26

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.

1.1.0 - 2023-05-15

Added

Streaming ListObjects has no limit in number of results returned (#733)
Add Homebrew release stage to goreleaser's release process (#716)

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)

1.0.1 - 2023-04-18

Fixed

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

1.0.0 - 2023-04-14

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)

0.4.3 - 2023-04-12

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.

0.4.2 - 2023-03-17

Fixed

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

0.4.1 - 2023-03-16

The v0.4.1 release includes everything in v0.4.0 which includes breaking changes, please read the v0.4.0 changelog entry for more details.

Fixed

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

0.4.0 - 2023-03-15

Note: the 0.4.0 release was held due to issues discovered after the release was cut.

Removed

[BREAKING] Disable schema 1.0 support, except if appropriate flags are set (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 (#625)
Add timeout flag to migrate command (#634)

Fixed

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

0.3.7 - 2023-02-21

Fixed

Contextual tuple propagation in the unoptimized ListObjects implementation (#565)

0.3.6 - 2023-02-16

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

0.3.5 - 2023-02-14

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 involving 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)

0.3.4 - 2023-02-02

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).

0.3.3 - 2023-01-31

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)

0.3.2 - 2023-01-18

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)

0.3.1 - 2022-12-19

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 (#422).

0.3.0 - 2022-12-12

This release comes with a few big changes:

Support for v1.1 JSON Schema

You can now write your models in the new DSL which the Playground and the syntax transformer can convert to the JSON syntax. Schema v1.1 allows for adding type restrictions to each assignable relation, and it can be used to indicate cases such as "The folder's parent must be a folder" (and so not a user or a document).
- This change also comes with breaking changes to how * and <type>:* are treated:
- <type>:* is interpreted differently according to the model version. v1.0 will interpret it as a object of type <type> and id *, whereas v1.1 will interpret is as all objects of type <type>.
- * is still supported in v1.0 models, but not supported in v1.1 models. A validation error will be thrown when used in checks or writes and it will be ignored when evaluating.
Additionally, the change to v1.1 models allows us to provide more consistent validation when writing the model instead of when issuing checks.

⚠️ Note that with this release models with schema version 1.0 are now considered deprecated, with the plan to drop support for them over the next couple of months, please migrate to version 1.1 when you can. Read more about migrating to the new syntax.

ListObjects changes

The response has changed to include the object type, for example:

{ "object_ids": [ "a", "b", "c" ] }

to

{ "objects": [ "document:a", "document:b", "document:c" ] }

We have also improved validation and fixed support for Contextual Tuples that were causing inaccurate responses to be returned.

ReadTuples deprecation

⚠️This endpoint is now marked as deprecated, and support for it will be dropped shortly. Please use Read with no tuple key instead.

0.2.5 - 2022-11-07

Security

Patches CVE-2022-39352

Added

Multi-platform container build manifests to releases (#323)

Fixed

Read RPC returns correct error when authorization model id is not found (#312)
Throw error if http.upstreamTimeout config is less than listObjectsDeadline (#315)

0.2.4 - 2022-10-24

Security

Patches CVE-2022-39340, CVE-2022-39341, and CVE-2022-39342

Fixed

TLS certificate config path mappings (#285)
Error message when a user field is invalid (#278)
host:port mapping with unspecified host (#275)
Wait for connection to postgres before starting (#270)

Added

Update Go to 1.19

0.2.3 - 2022-10-05

Added

Support for MySQL storage backend (#210). Thank you @MidasLamb!
Allow specification of type restrictions in authorization models (#223). Note: Type restriction is not enforced yet, this just allows storing them.
Tuple validation against type restrictions in Write API (#232)
Upgraded the Postgres storage backend to use pgx v5 (#225)

Fixed

Close database connections after migration (#252)
Race condition in streaming ListObjects (#255, #256)

0.2.2 - 2022-09-15

Fixed

Reject direct writes if only indirect relationship allowed (#114). Thanks @dblclik!
Log internal errors at the grpc layer (#222)
Authorization model validation (#224)
Bug in migrate command (#236)
Skip malformed tuples involving tuple to userset definitions (#234)

0.2.1 - 2022-08-30

Added

Support Check API calls on userset types of users (#146)
Add backoff when connecting to Postgres (#188)

Fixed

Improve logging of internal server errors (#193)
Use Postgres in the sample Docker Compose file (#195)
Emit authorization errors (#144)
Telemetry in Check and ListObjects APIs (#177)
ListObjects API: respect the value of ListObjectsMaxResults (#181)

0.2.0 - 2022-08-12

Added

ListObjects API

The ListObjects API provides a way to list all of the objects (of a particular type) that a user has a relationship with. It provides a solution to the Search with Permissions (Option 3) use case for access-aware filtering on smaller object collections. It implements the ListObjects RFC.

This addition brings with it two new server configuration options --listObjects-deadline and --listObjects-max-results. These configurations help protect the server from excessively long lived and large responses.

⚠️ If --listObjects-deadline or --listObjects-max-results are provided, the endpoint may only return a subset of the data. If you provide the deadline but returning all of the results would take longer than the deadline, then you may not get all of the results. If you limit the max results to 1, then you'll get at most 1 result.
Support for presharedkey authentication in the Playground (#141)

The embedded Playground now works if you run OpenFGA using one or more preshared keys for authentication. OIDC authentication remains unsupported for the Playground at this time.

0.1.7 - 2022-07-29

Added

migrate CLI command (#56)

The migrate command has been added to the OpenFGA CLI to assist with bootstrapping and managing database schema migrations. See the usage for more info.

➜ openfga migrate -h
The migrate command is used to migrate the database schema needed for OpenFGA.

Usage:
  openfga migrate [flags]

Flags:
      --datastore-engine string   (required) the database engine to run the migrations for
      --datastore-uri string      (required) the connection uri of the database to run the migrations against (e.g. 'postgres://postgres:password@localhost:5432/postgres')
  -h, --help                      help for migrate
      --version uint              the version to migrate to (if omitted the latest schema will be used)

0.1.6 - 2022-07-27

Fixed

Issue with embedded Playground assets found in the v0.1.5 released docker image (#129)

0.1.5 - 2022-07-27

Added

Support for defining server configuration in config.yaml, CLI flags, or env variables (#63, #92, #100)

v0.1.5 introduces multiple ways to support a variety of server configuration strategies. You can configure the server with CLI flags, env variables, or a config.yaml file.

Server config will be loaded in the following order of precedence:
- CLI flags (e.g. --datastore-engine)
- env variables (e.g. OPENFGA_DATASTORE_ENGINE)
- config.yaml
If a config.yaml file is provided, the OpenFGA server will look for it in "/etc/openfga", "$HOME/.openfga", or "." (the current working directory), in that order.
Support for grpc health checks (#86)

v0.1.5 introduces support for the GRPC Health Checking Protocol. The server's health can be checked with the grpc or HTTP health check endpoints (the /healthz endpoint is just a proxy to the grpc health check RPC).

For example,
```
grpcurl -plaintext \
  -d '{"service":"openfga.v1.OpenFGAService"}' \
  localhost:8081 grpc.health.v1.Health/Check
```
or, if the HTTP server is enabled, with the /healthz endpoint:
```
curl --request GET -d '{"service":"openfga.v1.OpenFGAService"}' http://localhost:8080/healthz
```
Profiling support (pprof) (#111)

You can now profile the OpenFGA server while it's running using the pprof profiler. To enable the pprof profiler set profiler.enabled=true. It is served on the /debug/pprof endpoint and port 3001 by default.
Configuration to enable/disable the HTTP server (#84)

You can now enable/disable the HTTP server by setting http.enabled=true/false. It is enabled by default.

Changed

Env variables have a new mappings.

Please refer to the .config-schema.json file for a description of the new configurations or openfga run -h for the CLI flags. Env variables are mapped by prefixing OPENFGA and converting dot notation into underscores (e.g. datastore.uri becomes OPENFGA_DATASTORE_URI).

Fixed

goroutine leaks in Check resolution. (#113)

0.1.4 - 2022-06-27

Added

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

0.1.2 - 2022-06-20

Added

Request validation middleware
Postgres startup script

0.1.1 - 2022-06-16

Added

TLS support for both the grpc and HTTP servers
Configurable logging formats including text and json formats
OpenFGA CLI with a preliminary run command to run the server

0.1.0 - 2022-06-08

Added

Initial working implementation of OpenFGA APIs (Check, Expand, Write, Read, Authorization Models, etc..)
Postgres storage adapter implementation
Memory storage adapter implementation
Early support for preshared key or OIDC authentication methods