Configuring OpenFGA

Refer to the OpenFGA Getting Started for info on the various ways to install OpenFGA.

The instructions below assume OpenFGA is installed and that you have the openfga binary in your PATH. If you have built openfga as a binary, but not in your path, you can refer to it directly (e.g. replace openfga in the instructions below with ./openfga or /path/to/openfga).

You can configure the OpenFGA server in three ways:

• Using a configuration file.
• Using environment variables.
• Using command line parameters.

If the same option is configured in multiple ways the command line parameters will take precedence over environment variables, which will take precedence over the configuration file.

The configuration options and their default values are defined in config-schema.json.

Using a configuration file

You can configure the OpenFGA server with a config.yaml file, which can be specified in either:

• /etc/openfga
• $HOME/.openfga
• . (i.e., the current working directory).

The OpenFGA server will search for the configuration file in the above order.

Here is a sample configuration to run OpenFGA with a Postgres database and using a preshared key for authentication:

datastore:
  engine: postgres
  uri: postgres://user:password@localhost:5432/mydatabase
authn:
  method: preshared
  preshared:
    keys: ["key1", "key2"]

Using environment variables

The OpenFGA server supports environment variables for configuration, and they will take priority over your configuration file. Each variable must be prefixed with OPENFGA_ and followed by your option in uppercase (e.g. --grpc-tls-key becomes OPENFGA_GRPC_TLS_KEY).

Using command line variables

Command line parameters take precedence over environment variables and options in the configuration file. They are prefixed with -- , e.g.

openfga run \
    --datastore-engine postgres \
    --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable'

Configuring data storage

OpenFGA supports multiple storage engine options, including:

• memory - A memory storage engine, which is the default. Data is lost between server restarts.
• postgres - A Postgres storage engine.
• mysql - A MySQL storage engine.
• sqlite - A SQLite storage engine.

The first time you run OpenFGA, or when you install a new version, you need to run the openfga migrate command. This will create the required database tables or perform the database migration required for a new version.

Postgres

openfga migrate \
    --datastore-engine postgres \
    --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable'

openfga run \
    --datastore-engine postgres \
    --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable'

To learn how to run in Docker, check our Docker documentation.

MySQL

The MySQL datastore has stricter limits for the max length of some fields for tuples compared to other datastore engines, in particular:

• object type is at most 128 characters (down from 256)
• object id is at most 128 characters (down from 256)
• user is at most 256 characters (down from 512)

The connection URI needs to specify the query parseTime=true.

openfga migrate \
    --datastore-engine mysql \
    --datastore-uri 'root:secret@tcp(mysql:3306)/openfga?parseTime=true'

openfga run \
    --datastore-engine mysql \
    --datastore-uri 'root:secret@tcp(mysql:3306)/openfga?parseTime=true'

To learn how to run in Docker, check our Docker documentation.

SQLite

openfga migrate
    --datastore-engine sqlite \
    --datastore-uri 'file:/path/to/openfga.db'

openfga run
    --datastore-engine sqlite \
    --datastore-uri 'file:/path/to/openfga.db'

To learn how to run in Docker, check our Docker documentation.

Configuring authentication

You can configure authentication in three ways:

• no authentication (default)
• pre-shared key authentication
• OIDC

Pre-shared key authentication

If using Pre-shared key authentication, you will configure OpenFGA with one or more secret keys and your application calling OpenFGA will have to set an Authorization: Bearer <YOUR-KEY-HERE> header.

Warning

If you are going to use this setup in production, you should enable HTTP TLS in your OpenFGA server. You will need to configure the TLS certificate and key.

Configuration File

Update the config.yaml file to

authn:
  method: preshared
  preshared:
    keys: ["key1", "key2"]
http:
  tls:
    enabled: true
    cert: /Users/myuser/key/server.crt
    key: /Users/myuser/key/server.key

Environment Variables

1. Configure the authentication method to preshared: export OPENFGA_AUTHN_METHOD=preshared.
2. Configure the authentication keys: export OPENFGA_AUTHN_PRESHARED_KEYS=key1,key2
3. Enable the HTTP TLS configuration: export OPENFGA_HTTP_TLS_ENABLED=true
4. Configure the HTTP TLS certificate location: export OPENFGA_HTTP_TLS_CERT=/Users/myuser/key/server.crt
5. Configure the HTTP TLS key location: export OPENFGA_HTTP_TLS_KEY=/Users/myuser/key/server.key

To learn how to run in Docker, check our Docker documentation.

OIDC

To configure with OIDC authentication, you will first need to obtain the OIDC issuer and audience from your provider.

Warning

If you are going to use this setup in production, you should enable HTTP TLS in your OpenFGA server. You will need to configure the TLS certificate and key.

Configuration File

Update the config.yaml file to

authn:
  method: oidc
  oidc:
    issuer: "oidc-issuer" # required
    issuerAliases: "oidc-issuer-1", "oidc-issuer-2" # optional
    audience: "oidc-audience" # required
    subjects: "valid-subject-1", "valid-subject-2" # optional

http:
  tls:
    enabled: true
    cert: /Users/myuser/key/server.crt
    key: /Users/myuser/key/server.key

Environment Variables

1. Configure the authentication method to OIDC: export OPENFGA_AUTHN_METHOD=oidc.
2. Configure the valid issuer (required): export OPENFGA_AUTHN_OIDC_ISSUER=oidc-issuer
3. Configure the valid issuer aliases (optional): export OPENFGA_AUTHN_OIDC_ISSUER_ALIASES=oidc-issuer-1,oidc-issuer-2
4. Configure the valid audience (required): export OPENFGA_AUTHN_OIDC_AUDIENCE=oidc-audience
5. Configure the valid subjects (optional): export OPENFGA_AUTHN_OIDC_SUBJECTS=oidc-subject-1,oidc-subject-2
6. Enable the HTTP TLS configuration: export OPENFGA_HTTP_TLS_ENABLED=true
7. Configure the HTTP TLS certificate location: export OPENFGA_HTTP_TLS_CERT=/Users/myuser/key/server.crt
8. Configure the HTTP TLS key location: export OPENFGA_HTTP_TLS_KEY=/Users/myuser/key/server.key

To learn how to run in Docker, check our Docker documentation.

Profiler (pprof)

Warning

Continuous profiling can be used in production deployments, but we recommend disabling it unless it is needed to troubleshoot specific performance or memory problems.

Profiling through pprof can be enabled on the OpenFGA server by providing the --profiler-enabled flag. For example:

openfga run --profiler-enabled

If you need to serve the profiler on a different port than the default 3001, you can do so by specifying the --profiler-addr flag. For example:

openfga run --profiler-enabled --profiler-addr :3002

If you want to run it in docker:

docker run -p 8080:8080 -p 8081:8081 -p 3000:3000 -p 3002:3002 openfga/openfga run --profiler-enabled --profiler-addr :3002

Health check

OpenFGA is configured with an HTTP health check endpoint /healthz and a gRPC health check grpc.health.v1.Health/Check, which is wired to datastore testing. Possible response values are

• UNKNOWN
• SERVING
• NOT_SERVING
• SERVICE_UNKNOWN

cURL

curl -X GET $FGA_API_URL/healthz

# {"status":"SERVING"}

gRPC

# See https://github.com/fullstorydev/grpcurl#installation
grpcurl -plaintext $FGA_API_URL grpc.health.v1.Health/Check

# {"status":"SERVING"}

Experimental features

Various releases of OpenFGA may have experimental features that can be enabled by providing the --experimentals flag or the experimentals config.

openfga run --experimentals="feature1, feature2"

or if you're using environment variables,

openfga -e OPENFGA_EXPERIMENTALS="feature1, feature2" run

The following table enumerates the experimental flags, a description of what they do, and the versions of OpenFGA the flag is supported in:

Name	Description	OpenFGA Version
otel-metrics	Enables support for exposing OpenFGA metrics through OpenTelemetry	0.3.2 <= v < 0.3.5
list-objects	Enables ListObjects API	0.2.0 <= v < 0.3.3
check-query-cache	Enables caching of check subproblem result	1.3.1 <= v < 1.3.6
enable-conditions	Enables conditional relationship tuples	1.3.8 <= v < 1.4.0
enable-modular-models	Enables modular authorization modules	1.5.1 <= v < 1.5.3
enable-list-users	Enables new ListUsers API	1.5.4 <= v < 1.5.6
enable-consistency-params	Enables consistency options	1.5.6 <= v < 1.6.0
enable-check-optimizations	Enables performance optimization on Check	1.6.2 <= v
enable-access-control	Enables the ability to configure and setup access control	1.7.0 <= v

Warning

Experimental features are not guaranteed to be stable and may lead to server instabilities. It is not recommended to enable experimental features for anything other than experimentation.

Experimental feature flags are also not considered part of API compatibility and are subject to change, so please refer to each OpenFGA specific release for a list of the experimental feature flags that can be enabled for that release.

Telemetry

OpenFGA telemetry data is collected by default starting on version v0.3.5. The telemetry information that is captured includes Metrics, Traces, and Logs.

note

Please refer to the docker-compose.yaml file as an example of how to collect Metrics and Tracing in OpenFGA in a Docker environment using the OpenTelemetry Collector. This should serve as a good example that you can adjust for your specific deployment scenario.

Metrics

OpenFGA metrics are collected with the Prometheus data format and exposed on address 0.0.0.0:2112/metrics.

Metrics are exposed by default, but you can disable this with --metrics-enabled=false (or OPENFGA_METRICS_ENABLED=false environment variable).

To set an alternative address, you can provide the --metrics-addr flag (OPENFGA_METRICS_ADDR environment variable). For example:

openfga run --metrics-addr=0.0.0.0:2114

To see the request latency per endpoint of your OpenFGA deployment, you can provide the --metrics-enable-rpc-histograms flag (OPENFGA_METRICS_ENABLE_RPC_HISTOGRAMS environment variable).

Tracing

OpenFGA traces can be collected with the OTLP data format.

Tracing is disabled by default, but you can enable this with the --trace-enabled=true (OPENFGA_TRACE_ENABLED=true environment variable). Traces will be exported by default to address 0.0.0.0:4317. You can change this address with the --trace-otlp-endpoint flag (OPENFGA_TRACE_OTLP_ENDPOINT environment variable).

To increase or decrease the trace sampling ratio, you can provide the --trace-sample-ratio flag (OPENFGA_TRACE_SAMPLE_RATIO env variable).

Tracing by default uses a insecure connection. You can enable TLS by using --trace-otlp-tls-enabled=true flag or the environment variable OPENFGA_TRACE_OTLP_TLS_ENABLED.

Warning

It is not recommended to sample all traces (e.g. --trace-sample-ratio=1). You will need to adjust your sampling ratio based on the amount of traffic your deployment receives. Higher traffic will require less sampling and lower traffic can tolerate higher sampling ratios.

Logging

OpenFGA generates structured logs by default, and it can be configured with the following flags:

• --log-format: sets the log format. Today we support text and json format.
• --log-level: sets the minimum log level (defaults to info). It can be set to none to turn off logging.

Warning

It is highly recommended to enable logging in production environments. Disabling logging (--log-level=none) can mask important operations and hinder the ability to detect and diagnose issues, including potential security incidents. Ensure that logs are enabled and properly monitored to maintain visibility into the application's behavior and security.

Related Sections

Check the following sections for more on how to use OpenFGA.

Production Best Practices

Learn the best practices of running OpenFGA in a production environment

• More