OpenFGA is an authorization service. Your applications stop carrying if user.role == "admin" logic and instead ask one central server whether a given user has a given relationship to a given object. The server answers from two things you control: an authorization model that says which relationships can exist, and relationship tuples that record which ones do.
It is for the question every multi-user system eventually hits: “who may see or change this particular thing?”, when the answer depends on teams, folders, organisations and sharing rather than on a single role.
CNCF daily · Sprint 5, post 9 of 14 · Security & Compliance
At a glance
| Category | Provisioning, subcategory Security & Compliance (CNCF Landscape) |
| CNCF status | Incubating. Joined as a Sandbox project in 2022 and moved to Incubating on 28 October 2025 (openfga.dev/project) |
| Origin | Created by the Auth0 FGA team; development continued at Okta before donation to CNCF. Auth0 FGA is the managed commercial service built on it |
| Inspired by | Google’s Zanzibar paper, using Relationship-Based Access Control (ReBAC), which also covers role-based access and, through conditions and contextual tuples, some attribute-based cases |
| Written in | Go. Single binary and a container image (openfga/openfga) |
| License | Apache-2.0 |
| Latest release I found | v1.18.0 (17 June 2026) with v1.18.1 listed after it on a mirror. A newer release may exist; check the releases page |
| APIs | HTTP on 8080, gRPC on 8081, optional Playground on 3000 |
| Datastores | PostgreSQL, MySQL, SQLite, and an in-memory store for non-production use |
| Tooling | Official SDKs, the fga CLI, a VS Code extension, a Terraform provider, an RFC process and sample stores |
The problem OpenFGA solves
Permissions outgrow roles. “Admin” and “viewer” work until a document can be shared with one person, a team, or everyone in a folder, and until a team lives inside an organisation. Each service then re-implements the rules slightly differently.
Authorization logic is scattered. The same rule ends up in a web app, a backend, a batch job and a reporting tool, and a change must be made everywhere.
Lists are the hard part. Checking one object is easy. Answering “which shipments can this user see?” without loading everything is where home-grown code breaks down.
OpenFGA keeps the rules in one model, the facts in one store, and gives every service the same Check and ListObjects calls.
Key concepts
| Term | Meaning |
|---|---|
| Store | A container for one authorization model history and its tuples. Data is not shared across stores; separate stores suit separate environments such as dev and prod |
| Authorization model | Type definitions that say which relations can exist between users and objects. Models are versioned; each version gets an ID |
| Type and relation | A type (document, team) has relations (viewer, editor, member). A relation can be direct, computed from another relation, or inherited from a parent object |
| Object | A type plus an identifier, such as document:roadmap |
| Relationship tuple | A fact written as user, relation, object, for example user:anne is editor of document:roadmap |
| Userset | A set of users such as team:platform#member, usable wherever a user can be |
| Check | “Does this user have this relation to this object?” Returns allowed true or false |
| ListObjects / ListUsers | “Which objects of this type can this user reach?” and “which users have this relation to this object?” |
| Expand | Shows the tree of users and usersets behind a relation, to explain a decision |
| Conditions | CEL-style expressions attached to a tuple, evaluated with request-time context, for example “not expired” |
| Contextual tuples | Tuples sent with one request that are treated as stored for that request only |
Architecture
The application asks; the server evaluates the model against stored tuples. Blue is the caller, purple is OpenFGA, green is the store and grey are supporting systems. Open the zoomable diagram, or download it as SVG or PNG.
| Component | Responsibility |
|---|---|
| OpenFGA server | Stateless Go service exposing the HTTP and gRPC APIs. Resolves Check, ListObjects, ListUsers and Expand against the model and tuples |
| Datastore | Holds stores, model versions and tuples. Bootstrapped and upgraded with openfga migrate |
| Your service | Enforces the answer. OpenFGA decides; the application allows or denies |
| Identity provider | Not part of OpenFGA. Its token claims, such as groups, can be passed as contextual tuples |
| CLI and CI | fga writes models, imports and exports data and runs model tests from store files |
Design principle. Separate the rules from the facts and keep both out of application code. The model changes rarely and is reviewed like code; the tuples change constantly and are written as users share things.
Model, facts, answer
Steps 1 and 2 are written once; steps 3 and 4 run on every request. Open the zoomable diagram, or download it as SVG or PNG.
- Write an authorization model to a store. It defines what relationships are possible.
- Write relationship tuples as users are granted access.
- A service sends a Check (or ListObjects) with the user, relation and object, and ideally the model ID.
- The server evaluates the model against the tuples and returns
allowedtrue or false. If the relation is not in the model the API returns a 400 error rather than false.
OpenFGA concepts · Perform a Check
Install OpenFGA
Commands follow the official setup guide. I did not run them here; pin image versions rather than using latest for anything shared.
Docker, for a first look
docker pull openfga/openfga
docker run -p 8080:8080 -p 8081:8081 -p 3000:3000 openfga/openfga run
That starts the HTTP API on 8080, gRPC on 8081 and the Playground on 3000 with default settings, including the in-memory datastore. Data is lost on restart.
Docker with Postgres
docker network create openfga
docker run -d --name postgres --network=openfga \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password postgres:17
docker run --rm --network=openfga openfga/openfga migrate \
--datastore-engine postgres \
--datastore-uri "postgres://postgres:password@postgres:5432/postgres?sslmode=disable"
docker run --name openfga --network=openfga -p 8080:8080 -p 8081:8081 openfga/openfga run \
--datastore-engine postgres \
--datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable'
The migrate step creates the tables and must be run first time and whenever you install a new version. The docs also give Docker Compose files for Postgres, MySQL and SQLite, and MySQL URIs need parseTime=true.
Kubernetes
The setup guide points to Kubernetes with an official Helm chart in the openfga/helm-charts repository. Check that repository’s README for the current repository URL and values, since I did not verify them. In Kubernetes, run migrate as a job before the server starts.
CLI
go install github.com/openfga/cli/cmd/fga@latest
The CLI is also available as a container (openfga/cli) and as OS packages from its releases page.
Using OpenFGA
Snippets are adapted from the official docs and are untested here.
A first model
model
schema 1.1
type user
type team
relations
define member: [user]
type folder
relations
define owner: [user]
define viewer: [user, team#member] or owner
type document
relations
define parent: [folder]
define editor: [user, team#member]
define viewer: [user, team#member] or editor or viewer from parent
Read it as: a document’s viewers are people granted viewing directly, members of a granted team, editors, or anyone who can view the parent folder. Permissions flow through the graph; you write a few facts and the model derives the rest.
Write tuples and check
export FGA_API_URL=http://localhost:8080
# create a store (note the id it returns)
fga store create --name demo
# write the model, then tuples
fga model write --store-id $FGA_STORE_ID --file model.fga
fga tuple write --store-id $FGA_STORE_ID user:anne member team:platform
fga tuple write --store-id $FGA_STORE_ID team:platform#member viewer folder:ops
fga tuple write --store-id $FGA_STORE_ID folder:ops parent document:runbook
fga query check --store-id $FGA_STORE_ID user:anne viewer document:runbook
The same call over HTTP:
curl -X POST $FGA_API_URL/stores/$FGA_STORE_ID/check \
-H "content-type: application/json" \
-d '{
"authorization_model_id": "'"$FGA_MODEL_ID"'",
"tuple_key": {"user": "user:anne", "relation": "viewer", "object": "document:runbook"}
}'
# {"allowed": true}
Without any tuples every check fails. The best-practice page strongly recommends passing the model ID because the server then avoids a database lookup for the latest model and behaves consistently until you choose to switch.
Time-limited access with a condition
type document
relations
define viewer: [user with non_expired_grant]
condition non_expired_grant(current_time: timestamp, grant_time: timestamp, grant_duration: duration) {
current_time < grant_time + grant_duration
}
A tuple carries grant_time and grant_duration as its context, and each Check supplies current_time. If current_time is omitted the Check fails. Condition context written with a tuple is limited to 32KB.
Group claims from a token as contextual tuples
{
"tuple_key": {"user": "user:anne", "relation": "viewer", "object": "document:launch"},
"contextual_tuples": {
"tuple_keys": [
{"user": "user:anne", "relation": "member", "object": "group:marketing"}
]
}
}
This avoids synchronising group membership into OpenFGA. The docs note the trade-off: access continues until the token expires even if the group changes. Up to 100 contextual tuples may be sent per request, and a contextual tuple overrides a stored tuple with the same user, relation and object.
List what a user can reach
fga query list-objects --store-id $FGA_STORE_ID user:anne viewer document
ListObjects returns the objects of a type the user has a relation to, and is the call for building filtered lists. If a Check says allowed: true, ListObjects may include that object.
Test models in CI
name: Model tests
model_file: ./model.fga
tuples:
- user: user:anne
relation: member
object: team:platform
tests:
- name: anne reads runbook through folder
check:
- user: user:anne
object: document:runbook
assertions:
viewer: true
fga model test --tests docs.fga.yaml
Store files can hold a model, tuples and check, list_objects and list_users tests, so model changes get a pull-request review and a test run like code.
Features
| Area | What you get |
|---|---|
| Modeling language | A readable DSL (JSON underneath) with direct relations, unions, intersections, exclusion (but not), parent inheritance (from), usersets and type-bound public access (user:*) |
| Query APIs | Check, BatchCheck (default batch size 50 in the SDK), ListObjects, ListUsers, Expand, Read |
| Conditions | Attribute-style rules on tuples evaluated with request context |
| Contextual tuples | Request-scoped facts for sessions, token claims, time and network context |
| Consistency option | Requests accept MINIMIZE_LATENCY (default) or HIGHER_CONSISTENCY |
| Multiple stores | Isolated data per environment or use case |
| Authentication | Pre-shared keys or OIDC for the server’s own API |
| Datastores | Postgres (with optional read replica via a secondary URI), MySQL, SQLite, memory |
| SDKs and tools | SDKs including JavaScript, Go, Python, Java and .NET, the CLI, VS Code extension, Terraform provider |
| Observability | Prometheus-style metrics and OpenTelemetry support, plus a pprof profiler option |
Configuration reference
Options can come from a config file, environment variables (prefix OPENFGA_, so datastore.engine becomes OPENFGA_DATASTORE_ENGINE) or flags. Flags win over environment variables, which win over the file.
| Option | Purpose |
|---|---|
datastore.engine, datastore.uri |
memory (default), postgres, mysql or sqlite and its connection string |
datastore.username, datastore.password |
Override credentials in the URI |
datastore.secondaryUri |
Read replica for Postgres |
datastore.maxCacheSize |
Authorization models held in memory (default 100000) |
authn.method |
none, preshared or oidc |
authn.preshared.keys |
Accepted API keys |
authn.oidc.issuer, audience |
OIDC validation settings |
http.tls.enabled, http.tls.cert, http.tls.key |
TLS for the HTTP API |
playground.enabled |
Local UI; for development only |
profiler.enabled |
pprof endpoint |
log.format |
For example json |
The full list is long and changes by release; use the configuration page for your version.
Production reference design
- Run several stateless server replicas behind a load balancer, all pointing at one database.
- Give OpenFGA its own database, in the same datacentre and network as the servers, created and upgraded only with
openfga migrate. - Tune Postgres connections. The docs advise setting minimum open and idle connections (idle must not exceed open) and dividing the database’s
max_connectionsacross replicas. - Turn the Playground off (
--playground-enabled=false). It performs any action on the server and works only on localhost. - Authenticate the API with OIDC or pre-shared keys, and use TLS.
- Pin the model ID in every call and promote new models deliberately.
- Keep PII out of tuples. Use stable opaque IDs.
- Use contextual tuples for fast-changing data and stored tuples for durable relationships.
Security
| Area | What to know |
|---|---|
| API access | Without authn configured the API is open. Use OIDC or pre-shared keys and TLS, and keep the server off public networks |
| Playground | Intended for local use; it can only run when authentication is none, which is why it must be off in production. The docs say it is deprecated and will be removed |
| Data hygiene | The best-practice guide says not to store personally identifiable information in tuples |
| Token-claim staleness | Access via claims in contextual tuples lasts until the token expires |
| Recent advisories | v1.14.0 fixed a case where BatchCheck calls with several checks for the same tuple could be enforced improperly (CVE-2026-34972). v1.13.1 fixed Check requests with conditions and caching returning incorrect cached results (CVE-2026-33729). For an authorization system, stay on a current release and read release notes |
| Model changes | A bad model change is a security change. Test models in CI and roll them out by model ID |
Monitoring and day-2 operations
| Task | How |
|---|---|
| Upgrade | Run openfga migrate with the new version before starting new servers; read the changelog for behaviour and security fixes |
| Change a model | Write a new model version, test it, then switch callers to the new model ID |
| Debug a decision | Use Expand to see the tree, or add the user and relation to a test in a store file |
| Backup | Back up the datastore; it holds everything |
| Scale reads | Add replicas; for Postgres add a secondary read datastore |
| Metrics | Scrape the metrics endpoint and watch latency by API; v1.14.0 added a storage iterator query duration histogram |
| Symptom | First checks |
|---|---|
| 400 on Check | The relation or type is not in the model you passed |
| Check is false unexpectedly | Missing tuple, wrong object ID, or a condition parameter absent from the request context |
| Check fails with a condition | current_time or another condition parameter missing from context |
| Slow Check or ListObjects | Model ID not specified, deep hierarchies, or database latency |
| Server will not start | Migration not run, or MinIdleConns greater than MinOpenConns |
Usage cases
- Document and folder sharing. Share with a person, a team or a whole folder and let access inherit.
- Multi-tenant SaaS. Organisation, project and resource hierarchies with role-like relations.
- Central authorization for microservices. One model and one answer for every service.
- Platform and infrastructure permissions. Who may deploy to which environment or view which cluster.
- Filtered lists. Use ListObjects so a user’s list contains only what they can see.
- Cold-chain sprint project. The Sprint 5 final project uses OpenFGA for per-shipment access for carriers and customers.
Operational considerations
- It decides, it does not enforce. Your services must call it and honour the answer, and must fail closed when it is unreachable.
- Another stateful dependency. The database is now critical to every protected request.
- Modeling takes thought. Deep or cyclic graphs are costly to evaluate, and the project’s release notes show repeated work on deep and wide hierarchies.
- Tuple lifecycle is your job. Writing and removing tuples as the business changes must be reliable, or access drifts.
- Not a policy-as-code engine. It models relationships; arbitrary attribute rules are limited to conditions and contextual tuples.
- Playground limits. It loads up to 100 tuples and does not support conditional or contextual tuples.
Adoption
The project site says it is used by Grafana, Docker and Canonical. The CNCF incubation application listed Canonical among three production examples and pointed to the community repository’s ADOPTERS.md plus many undisclosed users. Okta’s Auth0 FGA is the managed service built on it. I did not read the full adopters list.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| SpiceDB (AuthZed) | Zanzibar-based ReBAC with its own schema language, commercially backed | Teams wanting strict consistency controls and a vendor behind the engine |
| Permify | Zanzibar-style with a concise DSL, Postgres as a first-class backend | Smaller teams wanting a lighter start |
| Open Policy Agent | Policy-as-code with Rego, attribute-based | Infrastructure and Kubernetes admission style policies rather than shared-resource graphs |
| Cedar and Cerbos | Policy languages and engines | Policy-driven rules over attributes |
| Ory Keto | Zanzibar-inspired permissions in the Ory suite | Teams already using Ory |
| Hard-coded roles | Roles in application code | Small systems with few distinct permissions |
| Auth0 FGA | Managed service from the OpenFGA team | Teams that want a managed offering |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| Relationship model fits sharing, hierarchies and tenancy naturally | Requires learning a modeling language and maintaining tuples |
| CNCF Incubating, Apache-2.0, vendor-neutral governance | Large share of contributors come from one origin company |
| Readable DSL, strong SDK coverage, CLI testing in CI | Central dependency in the request path |
| Check, ListObjects, ListUsers and Expand cover decisions and lists | Deep graphs and large ListObjects need design care |
| Conditions and contextual tuples add attribute-style rules | Contextual tuples cap at 100 per request; condition context at 32KB |
| Runs on Postgres, MySQL or SQLite | Playground is deprecated and limited |
Project status and roadmap
OpenFGA was open sourced in June 2022 and joined CNCF as a Sandbox project that year. It became Incubating on 28 October 2025. Releases are frequent: v1.14.0 was dated 3 April 2026 and v1.18.0 17 June 2026, and the changelog shows ongoing work on cyclic and deep hierarchies, caching and BatchCheck. Design changes go through the openfga/rfcs repository. I did not find a single published roadmap page.
Recommendation
Adopt OpenFGA when several services share resources among users, teams and organisations and you want one auditable place for permission rules. Trial it first on one bounded domain such as document sharing, with the model under test in CI. Assess OPA or Cedar instead if your rules are mostly attribute policies rather than relationships, and SpiceDB if you need its consistency features. Before production: authenticate and encrypt the API, disable the Playground, pin the model ID, run replicas against a dedicated database and stay on a current release.
References: OpenFGA documentation · Concepts · Docker setup · Configuration options · Running in production · Conditions · Contextual tuples · Testing models · Tuple best practices · Project page · CNCF incubation announcement · CNCF project page

