Happy Dussehra! May good always win. Merry Christmas! Warm wishes from Vizag. Happy New Year! Here’s to a great year ahead.

DevOps · CNCF daily

OpenFGA: Fine-Grained Authorization Based on Relationships

CNCF Incubating. A Zanzibar-inspired authorization server where you describe permissions as relationships between users and objects, then ask it "can this user do this?" over HTTP or gRPC, with Postgres, MySQL or SQLite behind it.

17 min read

CNCF Incubating

  • OpenFGA
  • ReBAC
  • Zanzibar
  • Postgres
  • MySQL
  • gRPC
  • Docker
  • Kubernetes
CNCF project page

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

OpenFGA architecture: an application sends check and list requests to the OpenFGA server, which reads authorization models and relationship tuples from a Postgres, MySQL or SQLite datastore. An identity provider token supplies group claims the application can send as contextual tuples, and the FGA CLI and CI pipeline write models and run tests against the server.

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

OpenFGA flow: first an authorization model defines types and relations, then relationship tuples record facts between users and objects. A check request asks whether a user has a relation to an object, the server evaluates the model against the tuples, and returns allowed true or false to the calling service.

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.

  1. Write an authorization model to a store. It defines what relationships are possible.
  2. Write relationship tuples as users are granted access.
  3. A service sends a Check (or ListObjects) with the user, relation and object, and ideally the model ID.
  4. The server evaluates the model against the tuples and returns allowed true 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_connections across 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

Spotted something wrong or out of date?Suggest a correction. I review every suggestion before changing the page.