OpenFGA (openfga)

Fine grained authorisation server (Zanzibar model) answering the relationship checks of the Control Plane.

Generated from catalog/services/openfga.yaml: do not edit by hand.

Summary

Version	1.22.1
Use	install and configure, configure and connect
Layer	functional (AI catalog)
Category	Security and policies
Installation methods	binary, podman
External connection	no
Sandbox only	no

Licence

SPDX identifier	Apache-2.0
Licence policy	core licence (MIT or Apache-2.0)
Licence exception	-
Platform component	openfga

Packages and artifacts

A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.

Kind	Package	Version	Licence	Details
container image	docker.io/openfga/openfga	v1.22.1	Apache-2.0	image key openfga, used by migrate, openfga-server, digest sha256:b852071314f1fda1194d341a6ebac0a4f619b3cd87a6626d2ccc7048af4ec671
binary archive	openfga_1.22.1_linux_amd64.tar.gz	1.22.1	Apache-2.0	https://github.com/openfga/openfga/releases/download/v1.22.1/openfga_1.22.1_linux_amd64.tar.gz, x86_64, checksum sha256

Images are pinned by tag in the descriptor, and by digest when the descriptor declares one (the offline bundle then refuses a pulled image that does not carry it); the digest is recorded in the mirror of the Manager when the offline bundle is imported, and every pull or load is checked against it.

Supported systems and architectures

Method	Operating systems	Architectures
binary	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64 (architecture of the artifacts of the descriptor)
podman	RHEL family (dnf), Debian family (apt), Arch Linux (pacman)	x86_64, aarch64 (not restricted by the descriptor)

Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.

Prerequisites

Host

• at least 512 MB of memory (blocking, memory).

Network and ports

Component	Port name	Port	Opened in the host firewall
openfga-server	http	8080/tcp	yes
openfga-server	grpc	8081/tcp	yes
openfga-server	metrics	2112/tcp	yes

Services and connections needed

• database: postgresql.

Details and resolution: see Dependencies.

Installation methods and modes

Method	Default	What the method uses
binary	yes	the binary archives of the descriptor, unpacked under the service directory
podman	-	the container images of the descriptor, run by Podman under systemd

Components

Component	Kind	Installation methods	Ports
Schema migration (migrate)	one shot	binary, podman	-
OpenFGA server (openfga-server)	master	binary, podman	8080/tcp, 8081/tcp, 2112/tcp

In memory (sandbox) (memory)

One server, data kept in memory and lost at restart; no database.

What the mode deploys:

Component	Placement
migrate	not used
openfga-server	min 1, max 1

Single server (standalone) (default)

One server on PostgreSQL.

What the mode deploys:

Component	Placement
migrate	min 1, max 1
openfga-server	min 1, max 1

Replicated (replicated)

Several stateless servers on a shared PostgreSQL, behind the load balancer.

What the mode deploys:

Component	Placement
migrate	min 1, max 1
openfga-server	min 2, recommended 3

Install this service

The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.

1. Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.

2. Choose the service. On the Service step, select OpenFGA. The card shows the licence Apache-2.0 and the dependencies the installation needs. Pick the Method among binary, podman (default binary).

3. Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: memory, standalone (default), replicated. Each mode deploys the components listed in Installation methods and modes. With several components, place each one on its hosts in Component placement (Suggest placement proposes a placement that respects the cardinalities).

4. Bind the dependencies. On the Bindings step, choose for each dependency (database) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.

5. Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.

6. Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.

7. Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services. Open the service and choose Run the smoke test in the Checks card: Creates a store and a model, writes a relation, checks it is allowed and that another one is not, then deletes the store.

Connect an existing service

Schemes	https, http
Default port	8080
Authentication	optional
Health check	/healthz

Authentication method	Fields	Description
preshared	token	Pre-shared key of OPENFGA_AUTHN_PRESHARED_KEYS (authentication method preshared), the one the platform sends.
none	-	Method none (default of OpenFGA): any caller that reaches it reads and writes its tuples.

Official documentation: https://openfga.dev/docs/getting-started/setup-openfga/configure-openfga

Field	Type	Default	Description	Notes
Store id (store_id)	string	-	Store id used by the platform.	-

High availability

Cluster	replicas (replication)
High availability	external (external)
Failover	load balancer (load-balancer)
Replication	shared store (shared-store)
Quorum	none (none)
Discovery	none (none)
Entry point	load balancer (load-balancer)
Official documentation	https://openfga.dev/docs/best-practices/running-in-production
Peer TLS parameter	tls_enabled

Prerequisites

Prerequisite	Must be highly available	Modes	Description
database	yes	modes of level ha or cluster	Highly available PostgreSQL holding the authorization model and the tuples.

Topology per mode

Modes	Highest catalog level	Distribution	Quorum component	Fault domains	Description
memory	standalone (standalone)	single (single)	-	1	One server, data in memory, lost at restart.
standalone	standalone (standalone)	single (single)	-	1	One server on PostgreSQL.
replicated	ha (ha)	active-active (active-active)	-	2	Several stateless servers sharing PostgreSQL, behind the load balancer.

Configuration parameters

Network

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
HTTP port (http_port)	port	8080	-	no	no	yes	Port of the HTTP API and of /healthz.
gRPC port (grpc_port)	port	8081	-	no	no	yes	Port of the gRPC API.
Metrics port (metrics_port)	port	2112	-	no	no	yes	Prometheus port.
TLS (tls_enabled)	bool	false	-	no	no	yes	Serve the HTTP and gRPC APIs over TLS with a certificate of the manager CA.

Security

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Preshared key (preshared_key)	password	generated	-	no	yes	no	Bearer key of the API clients (EAI_OPENFGA_API_TOKEN of the Control Plane).

Logging

Parameter	Type	Default	Allowed values	Required	Secret	Restart	Description
Log level (log_level)	enum	info	debug, info, warn, error	no	no	no	Verbosity of the server log.

Dependencies

For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).

Binding	Provided by	Connection type	Endpoint	Optional	When nothing is bound	Description
database (standalone, replicated)	postgresql	postgresql	sql	no	postgresql is added to the installation	Datastore of the authorisation tuples and models.

Endpoints

Endpoint	Scheme	Component	Port	Path	TLS parameter	Binding parameters	Binding secrets	Provisioning command
http	http	openfga-server	8080 (http_port)	-	tls_enabled	-	token	-
grpc	grpc	openfga-server	8081 (grpc_port)	-	-	-	-	-

Client configuration files

Files rendered for the client configuration download:

• openfga.env (client.env.j2)

Commands

Command	Component	Target	Description
Migrate the schema (migrate)	openfga-server	first host	Applies the datastore migrations (PostgreSQL modes; required before every upgrade).

Health checks

Liveness (per instance)

Component	Check	Details
openfga-server	HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.http_port }}/healthz	Expected 200; 30 retries; interval 1 s; timeout 3 s

Readiness (service check)

Check	Details
HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn if config.tls_enabled else (host.ip or '127.0.0.1') }}:{{ config.http_port }}/healthz	Expected 200; 5 retries; interval 2 s; timeout 5 s

Smoke test

Creates a store and a model, writes a relation, checks it is allowed and that another one is not, then deletes the store. (openfga-server: create_store, write_model, write_tuple, check_allowed, check_denied, delete_store)

Preflight checks

Check	Type	Meaning	Severity	Components
memory	memory_mb {"min": 512}	at least 512 MB of memory	blocking	every component
http_port_free	port_free {"param": "http_port"}	port 8080 free on the host	blocking	openfga-server
grpc_port_free	port_free {"param": "grpc_port"}	port 8081 free on the host	blocking	openfga-server

Uninstall

Paths removed when the data is purged: {{ paths.log }}.

Quick links

• Metrics: http://{{ host.fqdn }}:{{ config.metrics_port }}/metrics

Upstream documentation

• Homepage: https://openfga.dev
• Source: https://github.com/openfga/openfga
• High availability: https://openfga.dev/docs/best-practices/running-in-production
• Authentication: https://openfga.dev/docs/getting-started/setup-openfga/configure-openfga