Service: OpenFGA - EyevinnOSC/community GitHub Wiki
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.
- Model and enforce fine-grained access control for your applications.
- Store authorization models and relationship tuples, and answer
checkrequests. - Keep stores and tuples across restarts or recreation of the instance, since all data is in PostgreSQL.
- Create a PostgreSQL instance (
serviceId: "birme-osc-postgresql", see Service: PostgreSQL) withcreate-service-instance: setPostgresPasswordand setPostgresDbtoopenfga; leave the user at its defaultpostgres. Wait until it is running. - Use
describe-service-instanceto read the internal cluster address, which has the form<tenant>-<name>.birme-osc-postgresql.svc.cluster.local. The database URL ispostgres://postgres:<password>@<tenant>-<name>.birme-osc-postgresql.svc.cluster.local:5432/openfga. Nosslmodeparameter is needed. OpenFGA creates and migrates the schema automatically on every start. - Generate an API key, for example
openssl rand -hex 24, and keep it somewhere safe. Every client must send it with each API call. - Store both values with
create-service-secret(serviceIdopenfga-openfga):fgadburl(the database URL) andfgakey(the API key). - 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).
| 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.
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. |
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.
-
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 addresshttp://<tenant>-<instance>.openfga-openfga.svc.cluster.local:8080, shown bydescribe-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.