Openfga

OpenFGA in Cloud-Native Engineering

Purpose and Use Cases

What Problem Does It Solve?

• Fine-grained authorization: Enables applications to define and enforce fine-grained access control policies
• Authorization as a service: Provides a dedicated authorization engine with low-latency policy evaluation
• Declarative authorization models: Define authorization using relationships and tuples
• Audit and compliance: Track authorization decisions for security audits
• Developer productivity: Eliminates authorization complexity in application code

When to Use

• Complex authorization requirements: When RBAC is insufficient and you need relationship-based access control
• Multi-tenant applications: When you need to enforce access control across multiple tenants
• Resource hierarchy: When you need to model resource hierarchies and inheritance
• Frequent authorization changes: When authorization policies change frequently and need to be versioned
• High-scale authorization: When you need to handle thousands of authorization requests per second

Key Use Cases

• Permission systems: Define who can access what resources
• Role hierarchies: Implement role inheritance and nested roles
• Team-based access: Control access based on team membership
• Audit logging: Track who accessed what and when
• API security: Protect APIs with fine-grained authorization

Architecture Design Patterns

Core Components

OpenFGA Server

openfga
├── server (HTTP/gRPC API)
├── storage (data store)
├── cache (decision caching)
├── analyzer (authorization analysis)
└── logger (decision logging)

• Server: HTTP/gRPC API for authorization operations
• Storage: Data store for authorization model and tuples
• Cache: Decision caching for performance
• Analyzer: Authorization analysis and debugging
• Logger: Authorization decision logging

Authorization Model (OpenFGA Model)

type user
  define viewer: [user]
  define editor: [user] or viewer
  define admin: [user] or editor

type document
  define viewer: [user]
  define editor: [user] or viewer
  define admin: [user] or editor
  define can_view: viewer or editor

• Type definitions: Define authorization types
• Relation definitions: Define relationships between types
• Computed relationships: Define derived relationships

Tuple Store

# Authorization tuples
(user:alice, viewer, document:doc1)
(user:bob, editor, document:doc2)
(user:charlie, admin, document:doc1)

• User: Subject making the request
• Relation: Relationship being checked
• Object: Object being accessed

Component Interactions

Application
    ↓ (Check API)
OpenFGA Server
    ↓ (Load model + tuples)
Storage
    ↓ (Evaluate)
Decision
    ↓ (Allow/Deny)
Application

Data Flow Patterns

Authorization Check Flow

1. Application receives request
2. Application calls OpenFGA Check API
3. OpenFGA loads authorization model
4. OpenFGA loads relevant tuples
5. OpenFGA evaluates authorization
6. OpenFGA returns allow/deny
7. Application enforces decision

Batch Authorization Flow

1. Application collects multiple checks
2. Application calls OpenFGA CheckMultiple API
3. OpenFGA evaluates all checks
4. OpenFGA returns batch results
5. Application processes batch results

Design Principles

Relationship-based Authorization

• What vs how: Define relationships, not authorization logic
• Reusability: Relationship definitions can be reused
• Maintainability: Authorization changes don't require code changes

Declarative Models

• Versioned models: Models are versioned and immutable
• Testable models: Models can be unit tested
• Readable models: Models should read like English

High Performance

• Efficient evaluation: Optimized for fast decision making
• Caching: Cache decisions for performance
• Batch operations: Support batch authorization checks

Integration Approaches

Integration with Other CNCF Projects

Kubernetes Integration

apiVersion: v1
kind: ConfigMap
metadata:
  name: openfga-authorization
data:
  model.fga: |
    type user
    type document
      relation viewer: [user]
      relation editor: [user]
      define can_view: viewer or editor

• Model stored as ConfigMap: Authorization model as Kubernetes resource
• Dynamic updates: Update model without application restart
• RBAC integration: Use Kubernetes RBAC for OpenFGA access

Istio Integration

apiVersion: networking.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: document-access
spec:
  action: CUSTOM
  provider:
    name: openfga
  rules:
    - to:
        - operation:
            paths: ["/documents/*"]

• Istio authorization: Use OpenFGA for Istio authorization
• Service-to-service: Enforce authorization between services
• API protection: Protect services with fine-grained authorization

OPA Integration

package istio.authorization

import input.request

# Check with OpenFGA
allow {
  http_send({
    "method": "POST",
    "url": "http://openfga:8080/check",
    "headers": [{"key": "Content-Type", "value": "application/json"}],
    "body": json.marshal({
      "tuple_key": {
        "user": sprintf("user:%s", [request.header["x-user-id"]]),
        "relation": "viewer",
        "object": sprintf("document:%s", [input.path[1]])
      }
    })
  }).status == 200
}

• OPA + OpenFGA: Combine OPA and OpenFGA for comprehensive policies
• Policy composition: Use OpenFGA for authorization, OPA for other policies

Kyverno Integration

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: enforce-openfga
spec:
  validationFailureAction: Enforce
  rules:
    - name: check-authorization
      match:
        any:
          - resources:
              kinds:
                - Pod
      validate:
        message: "Pod creation requires OpenFGA authorization"
        deny: {}

• Admission control: Enforce OpenFGA authorization
• Policy enforcement: Block unauthorized resource creation
• Automated checks: Automatically check OpenFGA before allowing

API Patterns

Check API

POST /stores/{store_id}/check
Content-Type: application/json

{
  "tuple_key": {
    "user": "user:alice",
    "relation": "viewer",
    "object": "document:doc1"
  }
}

Response:
{
  "allowed": true,
  "resolution": "Direct"
}

• tuple_key: The relationship being checked
• allowed: Whether the relationship exists
• resolution: How the decision was made

ListObjects API

POST /stores/{store_id}/list-objects
Content-Type: application/json

{
  "type": "document",
  "relation": "viewer",
  "user": "user:alice"
}

Response:
{
  "objects": ["document:doc1", "document:doc2"]
}

• type: Object type to list
• relation: Relationship to check
• user: User to check for
• objects: List of matching objects

ListRelations API

POST /stores/{store_id}/list-relations
Content-Type: application/json

{
  "object": "document:doc1",
  "user": "user:alice",
  "relations": ["viewer", "editor", "admin"]
}

Response:
{
  "relations": ["viewer", "admin"]
}

• object: Object to check
• user: User to check for
• relations: List of relations to check
• relations: List of matching relations

Configuration Patterns

OpenFGA Server Configuration

# OpenFGA config
store:
  driver: postgres
  postgres:
    conn_str: "postgresql://user:pass@localhost:5432/openfga?sslmode=disable"
    max_open_conns: 10
    max_idle_conns: 10

server:
  grpc:
    addr: "0.0.0.0:8081"
  http:
    addr: "0.0.0.0:8080"
    tls:
      enabled: true

logger:
  format: "json"
  level: "info"

metrics:
  enabled: true
  address: "0.0.0.0:9090"

Model Versioning

# Create new model version
openfga models write --store-id=<id> --model=model.json

# Query model
openfga models read --store-id=<id>

Extension Mechanisms

Custom Storage Backend

// Implement Storage interface
type CustomStorage struct {
    // Custom storage implementation
}

func (s *CustomStorage) FindTuples(ctx context.Context, key storage.TupleKey) ([]*openfgav1.Tuple, error) {
    // Implement tuple finding
}

func (s *CustomStorage) WriteTuples(ctx context.Context, store string, mutations []*openfgav1.TupleMutation) error {
    // Implement tuple writes
}

Decision Caching

cache:
  enabled: true
  ttl: "5m"
  max_size: 10000

Common Pitfalls and How to Avoid Them

Configuration Issues

Model Complexity

Problem: Authorization models become too complex and hard to maintain.

Solution:

• Break models into reusable components
• Use relationships instead of rules
• Document model design decisions
• Test models with OpenFGA analyzer

Performance Bottlenecks

Problem: Authorization checks are slow.

Solutions:

# Profile authorization checks
openfga analyze --store-id=<id> --model=model.json --tuple=user:alice,viewer,document:doc1

# Use caching
cache:
  enabled: true
  ttl: "5m"

Data Store Issues

Problem: Storage backend becomes bottleneck.

Solutions:

• Use connection pooling
• Implement read replicas
• Use in-memory cache
• Monitor storage performance

Performance Issues

High Latency

Problem: Authorization checks add latency to requests.

Solutions:

• Cache decisions
• Batch authorization checks
• Use async authorization
• Implement local authorization for simple cases

Scalability Issues

Problem: Cannot handle required request volume.

Solutions:

• Scale horizontally
• Implement caching layers
• Use efficient data structures
• Optimize storage queries

Operational Challenges

Model Updates

Problem: Model updates cause consistency issues.

Solutions:

• Version models
• Test model changes
• Use gradual rollouts
• Monitor for issues after updates

Debugging Authorization

Problem: Difficult to debug authorization decisions.

Solutions:

# Use analyze command
openfga analyze --store-id=<id> --model=model.json --tuple=user:alice,viewer,document:doc1

# Use trace command
openfga trace --store-id=<id> --model=model.json --tuple=user:alice,viewer,document:doc1

Data Migration

Problem: Data migration between versions.

Solutions:

• Test migrations in staging
• Implement migration scripts
• Keep old and new versions compatible
• Monitor migration progress

Security Pitfalls

Overly Permissive Models

Problem: Models allow more access than intended.

Solutions:

• Follow principle of least privilege
• Review models regularly
• Use audit logging
• Test models thoroughly

Secret Exposure

Problem: Authorization data exposed in logs.

Solutions:

• Redact sensitive data from logs
• Encrypt authorization data
• Use secure logging
• Audit log access

Injection Attacks

Problem: Malicious input bypasses authorization.

Solutions:

• Validate all input
• Use parameterized queries
• Implement input sanitization
• Audit authorization input

Coding Practices

Idiomatic Configuration

Standard Model Structure

# type definitions
type user
type group
  relation member: [user, group#member]
  define viewer: [user] or member
type document
  relation viewer: [user, group#viewer]
  relation editor: [user, group#editor]
  define can_view: viewer or editor

API Usage Patterns

Checking Authorization

# Check if user has access
openfga check --store-id=<id> --model=model.json \
  --tuple="user:alice,viewer,document:doc1"

Managing Tuples

# Write tuples
openfga write-tuples --store-id=<id> \
  --tuple="user:alice,viewer,document:doc1"

# Delete tuples
openfga delete-tuples --store-id=<id> \
  --tuple="user:alice,viewer,document:doc1"

Observability Best Practices

Metrics Collection

• Authorization requests: Count authorization requests
• Decision latency: Track authorization check latency
• Cache hit ratio: Monitor cache effectiveness
• Storage queries: Track storage query performance

Logging Strategy

• Decision logs: Record all authorization decisions
• Error logs: Log authorization errors
• Audit logs: Track who changed what models
• Access logs: Log authorization access patterns

Development Workflow

Model Development

1. Define authorization model
2. Write authorization tuples
3. Test with OpenFGA CLI
4. Verify with OpenFGA analyzer
5. Deploy to staging
6. Test in production with shadow mode
7. Enable in production

CI/CD Integration

# GitHub Actions example
- name: Validate Model
  run: openfga validate --model=model.fga

- name: Test Authorization
  run: openfga test --model=model.fga

- name: Deploy Model
  run: openfga models write --store-id=$OPENFGA_STORE_ID --model=model.fga

Fundamentals

Essential Concepts

Authorization Model

• Types: Define authorization types (user, document, etc.)
• Relations: Define relationships between types
• Computed Relationships: Define derived relationships
• Tuples: Store authorization relationships

Tuple-Based Authorization

• User: Subject making the request
• Relation: Relationship being checked
• Object: Object being accessed
• Tuple: Tuple of (user, relation, object)

Terminology Glossary

| Term | Definition |

|

Constraints

MUST DO

• Cite authoritative primary sources (official documentation, RFCs, standards bodies) — avoid secondary or blog references
• Include version-specific guidance when the reference topic has significant version-dependent behavior
• Structure reference content with clear navigation: overview first, then detailed subsections organized by use case
• Keep examples minimal and self-contained so readers can copy-paste without needing external context

MUST NOT DO

• Do not present opinionated practices as facts — distinguish between standards, recommendations, and personal preferences
• Avoid outdated API references or deprecated patterns; explicitly note version requirements for each code example
• Never include incomplete or pseudocode examples in reference materials — all examples should be runnable
• Do not conflate different product versions when documenting features that vary across releases