v1.5.4

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

v1.5.4-rc1

The v1.5.4-rc1 release is an experimental release candidate that introduces support for the ListUsers API. This endpoint answers the question "what users have relation X with object Y?". This can be used for use cases like share dialogues and notifying users on document changes.

This API can be enabled in the server by passing the --experimentals enable-list-users flag. Also note the OPENFGA_LIST_USERS_MAX_RESULTS, OPENFGA_LIST_USERS_DEADLINE and OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_USERS configuration options.

Note: This is not ready for production use. Currently outstanding issues:

• Excluded users are not supported, which impacts models that pair wildcards (e.g. user:*) with exclusion (e.g. but not)
• Chaining multiple exclusion (e.g. but not) operands may not return accurate set of results

Related resources:

• ListUsers API Documentation
• ListUsers RFC
• ListUsers Roadmap Item

v1.5.3

Added

• Apply tags to requests that have been intentionally throttled (#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 (#1517)

Changed

• Modular Models (Schema 1.2) support is enabled by default and the experimental flag for it has been dropped (#1520)
• Bumped to Go 1.21.9 (#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.

v1.5.2

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)

v1.5.1

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 release v1.5.4, in favour of request_duration_ms (#1450)

Contribution

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

v1.5.0

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 }

v1.4.3

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

v1.4.2

Fixed

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

v1.4.1

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

• Resolve rewrites involving exclusion (e.g. but not) more deterministically in Check (#1239)

• Record span errors correctly in Check, ListObjects, and StreamedListObjects (#1231)

• Log request validation errors correctly (#1236)

v1.4.0

Changed

• Enable support for Conditional Relationship Tuples by default. (#1220)

  ⚠️ Prior to upgrading to this release please first upgrade to v1.3.10, and then you can proceed with upgrading to this release. Rolling back from this release to a release prior to v1.3.9 has negative side-effects because of the introduction of Conditions. If you rollback from this release to a release prior to v1.3.9 then conditional relationship tuples will be treated unconditionally, because relationship tuples prior to v1.3.9 had no concept of Conditions.

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