OpenFGA Integration

docker/docker-compose-example-openfga.yml

@@ -1,5 +1,10 @@
-version: '3'
+name: opal-openfga-example
+
 services:
+  # When scaling the opal-server to multiple nodes and/or multiple workers, we use
+  # a *broadcast* channel to sync between all the instances of opal-server.
+  # Under the hood, this channel is implemented by encode/broadcaster.
+  # At the moment, the broadcast channel can be either: postgresdb, redis or kafka.
   broadcast_channel:
     image: postgres:alpine
     environment:
@@ -9,48 +14,65 @@ services:
     networks:
       - opal-network
 
+  # OPAL server configuration
+  # Handles policy updates and coordinates with the broadcast channel
   opal_server:
     image: permitio/opal-server:latest
     environment:
+      # the broadcast backbone uri used by opal server workers
       - OPAL_BROADCAST_URI=postgres://postgres:postgres@broadcast_channel:5432/postgres
+      # number of uvicorn workers to run inside the opal-server container  
       - UVICORN_NUM_WORKERS=4
+      # the git repo hosting our OpenFGA policy
       - OPAL_POLICY_REPO_URL=https://github.com/daveads/opal-example-policy-openfga
+      # polling interval of 30 seconds to check for policy updates
       - OPAL_POLICY_REPO_POLLING_INTERVAL=30
+      # configures initial data sources for the opal client
       - OPAL_DATA_CONFIG_SOURCES={"config":{"entries":[{"url":"http://opal_server:7002/policy-data","topics":["policy_data"],"dst_path":"/static"}]}}
       - OPAL_LOG_FORMAT_INCLUDE_PID=true
     ports:
+      # exposes opal server on the host machine at: http://localhost:7002
       - "7002:7002"
     depends_on:
       - broadcast_channel
     networks:
       - opal-network
 
+  # OPAL client configured specifically for OpenFGA integration
   opal_client_openfga:
     image: permitio/opal-client-openfga:latest
     environment:
       - OPAL_SERVER_URL=http://opal_server:7002
       - OPAL_LOG_FORMAT_INCLUDE_PID=true
+      # Configure OpenFGA as the policy engine
       - OPAL_POLICY_STORE_TYPE=OPENFGA
       - OPAL_POLICY_STORE_URL=http://0.0.0.0:8080
       - OPAL_OPENFGA_STORE_ID=01JAT34GM6T5WRVMXXDYWGSYKN
+      # Enable inline OpenFGA mode
       - OPAL_INLINE_OPENFGA_ENABLED=true
       #- OPAL_LOG_LEVEL=DEBUG
-
+      
     ports:
+      # exposes opal client API at: http://localhost:7766
       - "7766:7000"
+      # exposes OpenFGA API at: http://localhost:8080  
       - "8080:8080"
+      # Additional port exposure
       - "3000:3000"
     networks:
       - opal-network
     depends_on:
       - opal_server
+    # Ensures opal-server is ready before starting the client
     command: sh -c "exec ./wait-for.sh opal_server:7002 --timeout=20 -- ./start.sh"
     volumes:
       - openfga_backup:/opal/backup:rw
 
+# Network configuration for service communication
 networks:
   opal-network:
     driver: bridge
 
+# Volume for persisting OpenFGA data
 volumes:
   openfga_backup:

documentation/docs/tutorials/openfga.mdx

@@ -0,0 +1,105 @@
+# OpenFGA and OPAL
+
+[OpenFGA](https://openfga.dev) is an open-source authorization engine implementing the Zanzibar authorization model created by Google. OPAL provides realtime synchronization and management capabilities for OpenFGA, allowing you to keep your authorization data and relationships up-to-date across distributed OpenFGA instances.
+
+## Quick Start
+
+OPAL can run OpenFGA as a policy engine instead of OPA. To launch an example configuration with Docker-Compose:
+
+```bash
+git clone https://github.com/permitio/opal.git
+cd opal
+docker-compose -f docker/docker-compose-example-openfga.yml up -d
+```
+
+## Interacting with OpenFGA
+
+The OpenFGA API will be available at [http://localhost:8080](http://localhost:8080). Here are some key endpoints and operations:
+
+### Check Current State
+- View relationship tuples: `GET /stores/{store_id}/read`
+- List authorization models: `GET /stores/{store_id}/authorization-models`
+
+### Authorization Checks
+To check permissions, send a POST request to `/stores/{store_id}/check`:
+```json
+{
+  "tuple_key": {
+    "user": "user:anne",
+    "relation": "reader",
+    "object": "document:budget"
+  }
+}
+```
+
+### Setting Up Authorization Models
+Create or update an authorization model with PUT to `/stores/{store_id}/authorization-models`:
+```json
+{
+  "schema_version": "1.1",
+  "type_definitions": [
+    {
+      "type": "user"
+    },
+    {
+      "type": "document",
+      "relations": {
+        "reader": {
+          "this": {}
+        },
+        "writer": {
+          "this": {}
+        }
+      }
+    }
+  ]
+}
+```
+
+### Writing Relationship Tuples
+Add new relationships with a POST to `/stores/{store_id}/write`:
+```json
+{
+  "writes": {
+    "tuple_keys": [
+      {
+        "user": "user:anne",
+        "relation": "reader",
+        "object": "document:budget"
+      }
+    ]
+  }
+}
+```
+
+## Git Integration
+Instead of manually configuring authorization models and relationships, you can set the `OPAL_POLICY_REPO_URL` in your Docker compose configuration to automatically load configuration from a Git repository.
+
+## Key Features
+The OpenFGA integration with OPAL provides:
+- Automatic synchronization of authorization models across OpenFGA instances
+- Real-time updates to relationship tuples
+- Centralized management of authorization rules
+- Support for complex relationship-based authorization patterns
+- Version control integration for authorization configuration
+- Distributed deployment support with synchronization
+
+## Monitoring
+To view OPAL logs:
+```bash
+# Server logs
+docker-compose -f docker/docker-compose-example-openfga.yml logs opal_server
+
+# Client logs
+docker-compose -f docker/docker-compose-example-openfga.yml logs opal_client_openfga
+```
+
+Alternatively, you can also change the Docker-compose config and set your own policy git repo (the **OPAL_POLICY_REPO_URL** variable) to automatically load authorization models and relationship tuples from version control.
+
+For the server and client, respectively.
+
+The OpenFGA integration provides:
+- Automatic synchronization of authorization models across OpenFGA instances
+- Real-time updates to relationship tuples
+- Centralized management of authorization rules
+- Support for complex relationship-based authorization patterns