Getting Started

OpenFGA is an open source fine-grained authorization engine based on Google's Zanzibar model (relationship-based access control). You define an authorization model, write relationship tuples, and then ask check questions such as "can user:anne view document:roadmap?". Available as an open web service in Eyevinn Open Source Cloud, it stores all its data in a PostgreSQL database, so the OpenFGA instance itself is stateless.

Prerequisites

  • If you have not already done so, sign up for an Eyevinn OSC account
  • openssl and curl on your machine
  • An application running inside OSC (in your tenant) that calls the API, see Limitations

Step 1: Create a PostgreSQL database

Create an instance of the PostgreSQL service (see Service: PostgreSQL). Set a password and set PostgresDb to openfga. Leave the user at its default (postgres).

Open the instance details and note the internal cluster address, which has the form <tenant>-<name>.birme-osc-postgresql.svc.cluster.local. Your database URL is:

postgres://postgres:<password>@<tenant>-<name>.birme-osc-postgresql.svc.cluster.local:5432/openfga

No sslmode parameter is needed. OpenFGA creates and migrates the database schema automatically on every start.

Step 2: Generate an API key

Every client must send a preshared key with each API call. Generate one and keep it in your password manager:

openssl rand -hex 24

Step 3: Store the values as secrets

Navigate to the OpenFGA service and go to the "Service Secrets" tab. Click "New Secret" and create:

  • fgadburl: the PostgreSQL URL from Step 1
  • fgakey: the API key from Step 2

Step 4: Create the OpenFGA instance

Create an instance of the OpenFGA service and fill in:

Field Required Description
Name Yes Instance name, alphanumeric only
DatabaseUrl Yes {{secrets.fgadburl}}
PresharedKey Yes {{secrets.fgakey}}

Wait until the instance status is green and "running". Opening the instance URL in a browser shows an OpenFGA JSON 404 undefined_endpoint page. This is expected, see Limitations. The instance details show the internal address of the instance, which you use below.

Usage Example

These calls are made from an application inside your OSC tenant, using the internal address of the instance and the preshared key. Every call sends the headers Authorization: Bearer <preshared-key> and Content-Type: application/json.

Create a store (the name needs 3-64 letters, digits, spaces and . - / ^ _ & @). The response contains the store id:

curl -s -X POST http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080/stores \
  -H "Authorization: Bearer <preshared-key>" -H "Content-Type: application/json" \
  -d '{"name":"osc-test"}'

Write an authorization model:

curl -s -X POST http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080/stores/<store-id>/authorization-models \
  -H "Authorization: Bearer <preshared-key>" -H "Content-Type: application/json" \
  -d '{"schema_version":"1.1","type_definitions":[{"type":"user"},{"type":"document","relations":{"viewer":{"this":{}}},"metadata":{"relations":{"viewer":{"directly_related_user_types":[{"type":"user"}]}}}}]}'

Write a relationship tuple:

curl -s -X POST http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080/stores/<store-id>/write \
  -H "Authorization: Bearer <preshared-key>" -H "Content-Type: application/json" \
  -d '{"writes":{"tuple_keys":[{"user":"user:anne","relation":"viewer","object":"document:roadmap"}]}}'

Check access:

curl -s -X POST http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080/stores/<store-id>/check \
  -H "Authorization: Bearer <preshared-key>" -H "Content-Type: application/json" \
  -d '{"tuple_key":{"user":"user:anne","relation":"viewer","object":"document:roadmap"}}'

The answer is allowed: true for user:anne and allowed: false for a user without a tuple, such as user:bob. Without a valid key the API answers 401.

Configuration

Setting Required Description
DatabaseUrl Yes (sensitive) PostgreSQL URL, postgres://postgres:<password>@<internal-dns>:5432/openfga.
PresharedKey Yes (sensitive) The API key every client must send as Authorization: Bearer <key>. Generate with openssl rand -hex 24.

All data lives in PostgreSQL, so restarting or recreating the OpenFGA instance keeps your stores and tuples. Only the HTTP API on port 8080 is exposed.

Limitations

  • The API is reachable only from inside OSC. The OSC sign-in protects every path except /, and / is the only public path. Opening the instance URL therefore shows an OpenFGA 404 undefined_endpoint page, which is expected. Apps in your tenant call the API over the internal address http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080, shown in the instance details. Calls from outside OSC are redirected to the OSC sign-in, even with a valid key.
  • The gRPC port, the metrics port and the playground are not exposed.
  • No backup is configured. Back up the PostgreSQL instance if the data matters.
  • Not tested: calling the API from a My App, OIDC authentication, MySQL or SQLite, TLS to PostgreSQL, the gRPC API, very large models, upgrades to later OpenFGA versions, and using several preshared keys.

Resources