Skip to content

feat: add RFCs for unique store and model names #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
aaguiarz wants to merge 2 commits into
base: main
Choose a base branch
from
+74 −0
Draft

feat: add RFCs for unique store and model names #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1374e4b
feat: add RFCs for unique store and model names
aaguiarz Oct 28, 2024
70619b3
chore: added clarification
aaguiarz Oct 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions 20241028-unique-model-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Unique Model Names

## Meta

- **Name**: Unique Model Names
- **Start Date**: 2024-10-25
- **Last Updated Date**: 2024-10-25
- **Author(s)**: [aaguiarz](https://github.com/aaguiarz)
- **Status**: Draft
- **PR Link**:
- **Relevant Issues**:
- **Supersedes**: N/A

## Summary

When [creating a model](https://openfga.dev/api/service#/Authorization%20Models/WriteAuthorizationModel), OpenFGA does not allow to provide a name,and it will return a unique id.

This RFC proposes a way to specify a unique name when writing a model.

## Motivation

In some cases, developers would benefit from having an external identifier for the model.

For example, when deploying applications in development/staging environments a new model needs to be created in each deployment, and it desirable to have a predictable identifier for the model. Given OpenFGA creates a different Model ID each time, it's not possible. It needs to be stored in a secret storage vault, and retrieved at runtime, which adds friction. Some OpenFGA developers, for example, keep a database table that has a Github commit hash and the equivalent Model ID.

## Requirements

- It should be possible to upgrade to OpenFGA version that implements this feature without downtime.
- The OpenFGA [ReadAuthorizationModels endpoint](https://openfga.dev/api/service#/Authorization%20Models/ReadAuthorizationModels) endpoint should support filtering by name.
- The model name should be unique per store, not unique per OpenFGA instance.

## Proposed Solution

- Add a `name` parameter to the (https://openfga.dev/api/service#/Authorization%20Models/WriteAuthorizationModel).
Copy link
Copy Markdown

@3schwartz 3schwartz Nov 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Add a `name` parameter to the (https://openfga.dev/api/service#/Authorization%20Models/WriteAuthorizationModel).
- Add a `version` parameter to the (https://openfga.dev/api/service#/Authorization%20Models/WriteAuthorizationModel).

A suggestion for improvement: consider using “version” instead of “name” for identifying authorization models. While stores benefit from having unique names tied to their domain, authorization models are better suited to identification through meaningful versions, such as 1.0.1 → 1.0.2 or Git commit hashes. The store already provides the domain context.

Copy link
Copy Markdown

@OsmanMElsayed OsmanMElsayed Aug 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @aaguiarz,

I'm thinking - instead of constraining the API with one extra name property - it could be more flexible to make it possible for the consumers to add any number of tags (inspired by k8s labels).

This can open the possibility for multiple use-cases. E.g:

  • Use the tag to uniquely filter the authZ models by a unique tag known to the consumer. In this case the consumer can tag the model with the commit hash: commit-hash:1374e4b
  • Use the tag for rolling out an authZ model to a specific environment. In this case the tag can be release_approved. For this to work though, I'd imagine extra changes are needed to select the latest model that has a specific tag, instead of selecting the latest available model - in case the user does not specify the model ID when calling the check/list users/list resources APIs.

This will also address the comment above by letting the consumer decide how to structure/call the tags (version vs name etc..).

Wdyt?

Copy link
Copy Markdown

@couling couling Aug 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this current proposal gets us 90% of what we need. We can implement something akin to multiple tags simply by copying a model under multiple names. However for the last 10% we would (also?) need a tags model. Some requirements for a tags model are not met by this name model:

  • We need a way to roll out a model without restarting all services that reference it:

    • Tags should be (optionally) mutable, meaning a single tag may be moved to point to a different model at a later date. This allows multiple "latest" tags for blue-green deployments or feature flagging. Eg: models could be tagged with latest, stable, beta. And those tags would be expected to move.
    • check / read / write endpoints should support specifying a tag instead of an authorization model id. So when the tag moves, the corresponding requests would begin to use the new model.
    • consistency rules should ensure results to batch requests must only return results for a single authorization model.
    • consistency rules may allow delayed use of new models in check requests.

  • We need to be able to trace the origin(s) of an authorization model. We need to know which git commit, which PR, and which build generated a specific model. And currently json in ≠ json out, meaning we can't even to a text comparison.

    • Tags sharing the same authorization model should be discoverable. Eg: I might separately tag a model with the name of a git tag and a release number. I need to be able to find one tag using the other.
    • There should be a mechanism to retrospectivly tag a model. This enables flow from release-candidate to release without changing the model itself.

Copy link
Copy Markdown

@couling couling Aug 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear: I think this proposal would be great step forwards. I think a tags feature would also be useful. So I don't think the need for a tags feature would get in the way of proceeding with this unique name feature.

It's worth mentioning that openfga/roadmap#80 is titled "tagging" and references this RFC.

Copy link
Copy Markdown

@danielloader danielloader Aug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll echo above, I appreciate the concept of tags that can track a model in a way that means services don't need to be rolling reloaded to get model updates - this would make my kubernetes stack a tonne happier.

In fact anything that allows me to junk off the fragile and complicated CI system I have to use:

  • Model changes trigger pipeline
  • Pipeline pushes model to OpenFGA with a kubectl port-forward.
  • Takes the resulting new random model ID and writes it into a secret in the openfga namespace.
  • github.com/mittwald/kubernetes-replicator then replicates this annotated secret into multiple namespaces for applications to pickup (we have a monolithic model used by multiple microservices).
  • github.com/stakater/Reloader then detects the secret change and triggers a deployment rolling restart
  • Applications across the cluster restart and we hope all of the above worked so they point to the correct model id.

This is really unpleasant to deal with.

It's not much better in a docker compose local development stack either:

  • Start Postgres
  • Run OpenFGA migrations
  • Start OpenFGA
  • Run a custom init container with fga cli and jq in and a bash script with the model embedded
  • Create a store, then add the model to OpenFGA
  • Work out how to then take those FGA_MODEL_ID and FGA_STORE_ID values and use them in 4 other containers that get this configured via environment variables.

Anything that makes this somewhat less painful would be great - I was nearly going to implement a startup init script for each application to deduce these things via FGA CLI calls but stopped myself because that felt even worse.

- Validate that the name is unique. If a database constraint is used, a migration should be created that sets the Model Name = Model ID.
- Add a `name` parameter to the [ReadAuthorizationModels endpoint](https://openfga.dev/api/service#/Authorization%20Models/ReadAuthorizationModels).
38 changes: 38 additions & 0 deletions 20241028-unique-store-names.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Unique Store Names

## Meta

- **Name**: Unique Store Names
- **Start Date**: 2024-10-25
- **Last Updated Date**: 2024-10-25
- **Author(s)**: [aaguiarz](https://github.com/aaguiarz)
- **Status**: Draft
- **PR Link**:
- **Relevant Issues**:
- **Supersedes**: N/A

## Summary

When [creating a store](https://openfga.dev/api/service#/Stores/CreateStore), OpenFGA allows providing a store name, and it will return a unique id.

This RFC proposes a way to configure OpenFGA in a way that the store name can be unique.

## Motivation

In some cases, developers would benefit from having an external identifier for the store. Some examples are:

- The application is architected to use one store per tenant, and they need to map the internal tenant ID to the store ID.

- When deploying applications in development/staging environments a new store needs to be created in each deploy, and it desirable to have a predictable identifier for the store. Given OpenFGA creates a different Store ID each time, it's not possible. It needs to be stored in a secret storage vault, and retrieved at runtime, which adds friction

## Requirements

- Existing OpenFGA deployments that have duplicated names should still work.
- OpenFGA [GetStores endpoint](https://openfga.dev/api/service#/Stores/GetStore) endpoint should support filtering by name. Given it's possible that there could be more than one store with the same name, it needs to return an array. If the store name is unique, it will return an array with a single element.
Copy link
Copy Markdown

@kalleep kalleep Nov 13, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- OpenFGA [GetStores endpoint](https://openfga.dev/api/service#/Stores/GetStore) endpoint should support filtering by name. Given it's possible that there could be more than one store with the same name, it needs to return an array. If the store name is unique, it will return an array with a single element.
- OpenFGA [ListStores endpoint](https://openfga.dev/api/service#/Stores/ListStores) endpoint should support filtering by name. Given it's possible that there could be more than one store with the same name, it needs to return an array. If the store name is unique, it will return an array with a single element.


## Proposed Solution

- Add a configuration option to OpenFGA to enable unique store names.
- Add a `name` parameter to the [GetStores endpoint](https://openfga.dev/api/service#/Stores/GetStore) that returns an array of stores.
- Modify the storage adapters to validate that store names are unique when creating them. Given it is required to also support duplicated store names, we can't rely on database constraints.