OpenFGA

OpenFGA (serviceId openfga-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 ask check questions such as "can user:anne view document:roadmap?". It exposes HTTP and gRPC APIs. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance that stores all data in PostgreSQL, so the instance itself is stateless. License: Apache-2.0.

What it can do

  • Model and enforce fine-grained access control for your applications.
  • Store authorization models and relationship tuples, and answer check requests.
  • Keep stores and tuples across restarts or recreation of the instance, since all data is in PostgreSQL.

Creating an instance

  1. Create a PostgreSQL instance (serviceId: "birme-osc-postgresql", see Service: PostgreSQL) with create-service-instance: set PostgresPassword and set PostgresDb to openfga; leave the user at its default postgres. Wait until it is running.
  2. Use describe-service-instance to read the internal cluster address, which has the form <tenant>-<name>.birme-osc-postgresql.svc.cluster.local. The 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 schema automatically on every start.
  3. Generate an API key, for example openssl rand -hex 24, and keep it somewhere safe. Every client must send it with each API call.
  4. Store both values with create-service-secret (serviceId openfga-openfga): fgadburl (the database URL) and fgakey (the API key).
  5. Create the instance with create-service-instance, serviceId: "openfga-openfga":
{ "name": "myfga", "DatabaseUrl": "{{secrets.fgadburl}}", "PresharedKey": "{{secrets.fgakey}}" }

Wait for it to be running (wait-for-service-ready or get-instance-status). describe-service-instance shows the internal address of the instance. Opening the instance URL in a browser shows an OpenFGA JSON 404 undefined_endpoint page; this is expected (see Limitations).

Options

Option Required Type Meaning
name Yes string Name of the instance. Letters, digits and underscore only (^\w+$), at most 20 characters.
DatabaseUrl Yes string, sensitive PostgreSQL connection URL of the datastore, postgres://user:password@host:5432/dbname. Schema is created and migrated on every start. Feeds OPENFGA_DATASTORE_URI.
PresharedKey Yes string, sensitive API key every client must send as Authorization: Bearer <key>. Without a valid key API calls are rejected with 401; only /healthz needs no key. Feeds OPENFGA_AUTHN_PRESHARED_KEYS.

Store both options as service secrets and pass them as {{secrets.NAME}} (whole field value only). Overwriting a secret does not restart a running instance. Only the HTTP API on port 8080 is exposed.

PostgreSQL options

birme-osc-postgresql (https://app.osaas.io/dashboard/service/birme-osc-postgresql) is a long-running PostgreSQL instance. License: MIT.

Option Required Type Meaning
name Yes string Name of the instance (^\w+$, at most 20 characters).
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser. Use a secret, for example {{secrets.postgrespwd}}.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Name of the default database created at startup. Defaults to the user name.
PostgresInitDbArgs No string Extra arguments for initdb at cluster initialization (for example encoding or locale).
PostgresInitDbSql No string SQL executed during initialization.

Using the instance

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 (name of 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.

Limitations

  • The API is reachable only from inside OSC. The OSC sign-in protects every path except /, and / is the only public path. Apps in your tenant call the API over the internal address http://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080, shown by describe-service-instance. 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.

Resources