OpenFGA Operator

A security-first Kubernetes operator for managing OpenFGA instances with enterprise-grade protection against malicious code injection and comprehensive security controls.

Overview

The OpenFGA Operator provides a Kubernetes-native way to deploy and manage OpenFGA (Fine-Grained Authorization) instances with industry-leading security features. Built with a security-first approach, it implements comprehensive admission controllers, malicious code analysis, and cryptographic verification systems to ensure the highest level of security for authorization infrastructure.

🛡️ Security Features

Advanced Security Architecture

Admission Controller Framework: Comprehensive validation webhook system with policy enforcement
Malicious Code Injection Analysis: AI-powered static and dynamic security analysis
Git Commit Verification: Cryptographic GPG signature verification for all commits
Developer Authentication: Multi-factor authentication with certificate-based validation
Container Image Security: Vulnerability scanning and signature verification
Zero Trust Architecture: No implicit trust, continuous verification of all components

Security by Design

Defense in Depth: Multiple layers of security controls
Supply Chain Security: End-to-end security for deployment pipeline
Behavioral Analysis: ML-based anomaly detection and threat intelligence
Automated Incident Response: Self-healing security violations
Compliance Ready: SOC 2, ISO 27001, and NIST framework compliance

🚀 Core Features

Security-First Design: Comprehensive security architecture with admission controllers
Custom Resource Definition (CRD): Define OpenFGA instances using Kubernetes-native resources
Automatic Resource Management: Creates and maintains Deployments and Services for OpenFGA instances
Configurable Datastores: Support for memory, PostgreSQL, and MySQL datastores
Playground Support: Optional OpenFGA playground interface
Status Tracking: Real-time status updates and conditions
Enterprise Ready: Multi-tenancy, SSO integration, and compliance automation

Documentation

📚 Comprehensive Documentation

Alpha Release Guide: Complete deployment and usage guide for v0.1.0-alpha
Security Architecture: Detailed security design and implementation
Design Documentation: Complete system architecture and design patterns
Product Roadmap: Strategic vision and release planning
Product Log: Comprehensive product documentation
Security Policy: Security requirements and standards
Incident Response: Security incident response procedures

🌐 AuthCore Showcase

AuthCore Website: Professional showcase website with content management
Live Demo: AuthCore Demo - Interactive demonstration
Stakeholder Presentation: Comprehensive demo for business stakeholders

🎯 Demo Applications

Banking Application Demo: Complete banking microservice with fine-grained authorization
GenAI RAG Agent Demo: AI-powered RAG agent with OpenFGA authorization
Demo Deployment Scripts: Comprehensive deployment automation for all demo applications
Demo Overview: Introduction to all demonstration applications
Demo Deployment Scripts: Automated deployment scripts for local testing
Quick Start Guide: 5-minute demo setup guide

🚀 Quick Demo Deployment

Docker Compose (Recommended for Local Development):

# Deploy all demo applications with Docker Compose
./scripts/minikube/deploy-demos-docker.sh

# Access the applications:
# Banking App: http://localhost:3001
# GenAI RAG Agent: http://localhost:8001/docs
# OpenFGA API: http://localhost:8080

Minikube Deployment:

# Deploy operator first (if not already deployed)
./scripts/minikube/deploy-operator.sh

# Deploy all demo applications
./scripts/minikube/deploy-demos.sh

# Validate deployment
./scripts/minikube/validate-demos.sh

Windows PowerShell:

# Deploy all demo applications
.\scripts\minikube\deploy-demos.ps1

# Deploy specific applications
.\scripts\minikube\deploy-demos.ps1 -Banking  # Banking app only
.\scripts\minikube\deploy-demos.ps1 -GenAI    # GenAI app only

Prerequisites

Kubernetes cluster (v1.20+)
kubectl configured to access your cluster
Rust (1.70+) for development
Container runtime: Docker or Podman

Installation

Quick Start with Minikube

For local development and testing, use our comprehensive Minikube guides:

Minikube Setup Guide - Complete setup instructions
MacOS Guide - Step-by-step setup for macOS
Linux Guide - Step-by-step setup for Linux
Windows Guide - Step-by-step setup for Windows

🔐 HashiCorp Vault Integration

The OpenFGA Operator now supports HashiCorp Vault for secure secrets management in local development environments:

HashiCorp Vault Guide - Complete Vault integration setup
Auto-unseal Development Setup - Ready-to-use Vault configuration for local dev
Vault Secrets Operator (VSO) - Automatic secret synchronization to Kubernetes
PostgreSQL Secret Management - Database credentials managed through Vault
One-command Deployment - Automated setup script for complete environment

Quick Vault Setup

Deploy a complete development environment with HashiCorp Vault:

# Complete automated deployment with Vault
./scripts/deploy-minikube-vault.sh

This script provides:

HashiCorp Vault with auto-unseal for development
Vault Secrets Operator (VSO) for automatic secret sync
PostgreSQL with Vault-managed secrets instead of hardcoded passwords
OpenFGA with secure database connections using Vault secrets
Demo secrets initialization for immediate development
Port forwarding setup for easy access to all services

Manual Secret Management

Use the provided secret management script for easy Vault operations:

# Initialize Vault with demo secrets
./scripts/manage-vault-secrets.sh init

# View current PostgreSQL credentials
./scripts/manage-vault-secrets.sh get-postgres

# Update PostgreSQL password
./scripts/manage-vault-secrets.sh set-postgres --username myuser --password newpass

# Rotate PostgreSQL password automatically
./scripts/manage-vault-secrets.sh rotate-postgres

# Check Vault and Kubernetes status
./scripts/manage-vault-secrets.sh status

Access URLs:

Vault UI: http://localhost:8200/ui (token: root)
OpenFGA API: http://localhost:8080
OpenFGA Playground: http://localhost:3000

Automated Setup Scripts

For reliable deployment, we recommend using our consolidated deployment script with comprehensive container runtime support:

# Consolidated deployment script (recommended)
./scripts/minikube/deploy-operator.sh

This interactive script offers:

Registry-based deployment (recommended): Uses pre-built images from GitHub Container Registry
Local build deployment: Builds images locally for development with Docker/Podman support
Container runtime auto-detection: Supports both Docker and Podman
Alpha and latest image tags: Supports both latest and 0.1.0-alpha image tags
Interactive and non-interactive modes: Flexible deployment options
Comprehensive validation: Ensures successful deployment

Non-Interactive Deployment Options

For automated or CI/CD deployment:

# Registry-based deployment with latest tag
./scripts/minikube/deploy-operator.sh --registry-deploy

# Registry-based deployment with alpha tag
./scripts/minikube/deploy-operator.sh --registry-deploy --alpha

# Local build deployment with specific container runtime
./scripts/minikube/deploy-operator.sh --local-deploy --container-runtime podman

# Custom registry and tag
./scripts/minikube/deploy-operator.sh --registry-deploy --registry your-registry.com/operator --image-tag v1.0.0

Manual Makefile Targets

For direct control over deployment method:

# Registry-based deployment (recommended for reliability)
make minikube-setup-and-deploy-registry

# Local build deployment (for development)
make minikube-setup-and-deploy-local

# Validate deployment
make minikube-validate

Platform-Specific Instructions

# Linux/macOS - Setup Minikube first
./scripts/minikube/setup-minikube.sh

# Then deploy using consolidated script
./scripts/minikube/deploy-operator.sh

# Or deploy manually with environment variables
IMAGE_TAG=0.1.0-alpha make minikube-setup-and-deploy-registry  # Alpha release
# OR
CONTAINER_RUNTIME=podman make minikube-setup-and-deploy-local   # Local with Podman

# Validate deployment
./scripts/minikube/validate-deployment.sh

# Windows PowerShell - Setup Minikube first
.\scripts\minikube\setup-minikube.ps1

# Then deploy (enhanced script not yet available for PowerShell)
make minikube-setup-and-deploy-registry  # Recommended
# OR
make minikube-setup-and-deploy-local     # For development

# Validate deployment
.\scripts\minikube\validate-deployment.ps1

Deployment Methods Comparison

Method	Reliability	Speed	Use Case
Registry-based	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	Production, Testing, CI/CD
Local build	⭐⭐⭐	⭐⭐	Development, Custom changes

The registry-based approach resolves the "image is not known and cannot be cached" issues by using pre-built, tested images from GitHub Container Registry.

Production Installation

Deploy Alpha Release (Recommended)

For the alpha release, you can deploy directly from the container registry:

# Install CRDs
make install-crds

# Deploy from registry (easiest method)
IMAGE_TAG=v0.1.0-alpha make minikube-deploy-registry

# Or pull and deploy manually
docker pull ghcr.io/jralmaraz/authcore-openfga-operator:v0.1.0-alpha
kubectl apply -f k8s/

Install CRDs

make install-crds

Deploy the Operator

# Option 1: Deploy from registry (recommended for alpha)
IMAGE_TAG=v0.1.0-alpha make minikube-deploy-registry

# Option 2: Build and deploy locally
make build
make container-build
make minikube-deploy-local

# Option 3: Manual deployment
kubectl apply -f k8s/

Container Runtime Support

The OpenFGA Operator supports both Docker and Podman as container runtimes, providing flexibility to choose based on your preferences and licensing requirements.

Automatic Runtime Detection

The scripts and build system automatically detect available container runtimes:

# The system will automatically use Docker if available, otherwise Podman
make container-build

# Check which runtime will be used
make detect-runtime

Runtime Selection

You can explicitly specify which runtime to use:

Environment Variable:

export CONTAINER_RUNTIME=podman
make container-build
./scripts/minikube/setup-minikube.sh

Command Line Options:

# Shell scripts
./scripts/minikube/setup-minikube.sh --runtime podman

# PowerShell scripts
.\scripts\minikube\setup-minikube.ps1 -Runtime podman

Runtime Installation

The setup scripts can install either runtime based on your preference:

Docker: The default option with comprehensive support across all platforms
Podman: Open-source alternative with rootless execution capabilities

See the Minikube Setup Guide for detailed installation instructions.

Podman Specific Configuration

For detailed information about using Podman, including permission handling and troubleshooting, see the Podman Compatibility Guide.

Usage

Basic Example

Create an OpenFGA instance with in-memory storage:

apiVersion: authorization.openfga.dev/v1alpha1
kind: OpenFGA
metadata:
  name: my-openfga
  namespace: default
spec:
  replicas: 2
  image: "openfga/openfga:latest"
  datastore:
    engine: "memory"
  grpc:
    port: 8081
  http:
    port: 8080

PostgreSQL Example

Create an OpenFGA instance with PostgreSQL storage:

apiVersion: authorization.openfga.dev/v1alpha1
kind: OpenFGA
metadata:
  name: openfga-postgres
  namespace: default
spec:
  replicas: 3
  image: "openfga/openfga:v1.4.0"
  datastore:
    engine: "postgres"
    uri: "postgresql://user:password@postgres:5432/openfga"
  playground:
    enabled: true
    port: 3000
  grpc:
    port: 8081
  http:
    port: 8080

Demo Applications Deployment

For local testing and demonstrations, use our automated deployment scripts to quickly deploy fully functional demo applications with OpenFGA authorization:

Quick Demo Setup

# Deploy both banking and GenAI RAG demos with one command
./scripts/deploy-demos.sh

# Or deploy individual demos
./scripts/deploy-banking-demo.sh  # Banking application
./scripts/deploy-genai-demo.sh    # GenAI RAG agent

Demo Applications Overview

Banking Demo: Role-based authorization for financial services with accounts, transactions, and loans
GenAI RAG Demo: Knowledge base access control for AI applications with document-level permissions

Access Demo Applications

# Banking Demo (after deployment)
kubectl port-forward service/banking-demo-service 3000:80
curl http://localhost:3000/api/accounts

# GenAI RAG Demo (after deployment)  
kubectl port-forward service/genai-rag-agent-service 8000:80
curl -H 'x-user-id: alice' http://localhost:8000/api/knowledge-bases

Demo Management

# Check demo status
./scripts/deploy-demos.sh --status

# Test existing deployments
./scripts/deploy-demos.sh --test-only

# Clean up all demos
./scripts/deploy-demos.sh --cleanup

For detailed information, see:

Demo Deployment Scripts Documentation
Quick Start Guide
Banking Demo Details
GenAI RAG Demo Details

Cleanup and Uninstallation

When you need to completely remove the OpenFGA operator and all its resources from your cluster, use the comprehensive cleanup script:

Automated Cleanup (Recommended)

# Complete cleanup with confirmation prompt
scripts/minikube/cleanup-operator.sh

# Quick cleanup without confirmation
scripts/minikube/cleanup-operator.sh --force

# Cleanup but keep CRDs for faster re-deployment
scripts/minikube/cleanup-operator.sh --keep-crds

# Preview what would be deleted (dry run)
scripts/minikube/cleanup-operator.sh --dry-run

# Show current operator resource status
scripts/minikube/cleanup-operator.sh --status

What Gets Cleaned Up

The cleanup script removes:

✅ All OpenFGA custom resources (instances)
✅ Demo applications (banking-app, genai-rag-agent)
✅ Operator deployment and services
✅ ServiceAccount, ClusterRole, ClusterRoleBinding
✅ openfga-system namespace (optional)
✅ OpenFGA CRDs (optional)
✅ Running port-forwards

Selective Cleanup Options

# Keep namespace for faster re-deployment
scripts/minikube/cleanup-operator.sh --keep-namespace

# Skip demo cleanup (operator only)
scripts/minikube/cleanup-operator.sh --skip-demos

# Keep both namespace and CRDs
scripts/minikube/cleanup-operator.sh --keep-crds --keep-namespace

This automated approach ensures complete cleanup with proper error handling and provides options for different scenarios, from complete removal to selective cleanup for development workflows.

Security Implementation

Admission Controller Setup

The OpenFGA Operator includes a comprehensive admission controller for security validation:

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionWebhook
metadata:
  name: openfga-security-validator
spec:
  clientConfig:
    service:
      name: openfga-operator-webhook
      namespace: openfga-system
      path: "/validate"
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["authorization.openfga.dev"]
    apiVersions: ["v1alpha1"]
    resources: ["openfgas"]

Git Commit Verification

Enable GPG signature verification for all commits:

# Configure Git signing
git config --global user.signingkey YOUR_GPG_KEY_ID
git config --global commit.gpgsign true

# Pre-commit hook for verification
#!/bin/bash
if ! git verify-commit HEAD; then
    echo "ERROR: Commit must be signed with GPG"
    exit 1
fi

Security Policy Configuration

apiVersion: v1
kind: ConfigMap
metadata:
  name: openfga-security-policy
  namespace: openfga-system
data:
  policy.yaml: |
    securityPolicy:
      imageVerification:
        enforced: true
        allowedRegistries:
          - "gcr.io/openfga"
          - "quay.io/openfga"
      developerAuth:
        enforced: true
        requiredSignatures: ["gpg"]
      vulnerabilityScanning:
        enforced: true
        maxSeverity: "medium"

Configuration

OpenFGA Spec

Field	Type	Description	Default
`replicas`	`int32`	Number of OpenFGA replicas	`1`
`image`	`string`	OpenFGA Docker image	`openfga/openfga:latest`
`datastore`	`DatastoreConfig`	Datastore configuration	Required
`playground`	`PlaygroundConfig`	Playground configuration	Optional
`grpc`	`GrpcConfig`	gRPC server configuration	Optional
`http`	`HttpConfig`	HTTP server configuration	Optional

Datastore Configuration

Field	Type	Description	Default
`engine`	`string`	Datastore engine (`memory`, `postgres`, `mysql`)	`memory`
`uri`	`string`	Database connection URI (required for postgres/mysql)	`nil`

Playground Configuration

Field	Type	Description	Default
`enabled`	`bool`	Enable the playground interface	`false`
`port`	`int32`	Playground server port	`3000`

Development

Building

# Check syntax
make compile

# Build release binary
make build

# Run tests
make test

# Format code
make fmt

# Run linter
make clippy

# Run all checks
make check-all

Running Locally

# Install CRDs first
make install-crds

# Run the operator locally
make run

Development Mode

# Run with auto-reload (requires cargo-watch)
make dev

CI/CD

The project includes GitHub Actions workflows for:

Compile Check: Validates code compilation
Build Check: Validates release build
Test Suite: Runs unit tests
Format Check: Validates code formatting
Clippy Check: Runs Rust linter

These checks run automatically on pull requests and provide status checks.

Project Structure

├── src/
│   ├── main.rs           # Application entry point
│   ├── types.rs          # Custom Resource Definitions and types
│   └── controller.rs     # Controller logic and reconciliation
├── crds/                 # CRD YAML definitions
│   └── openfga-crd.yaml
├── k8s/                  # Kubernetes manifests
├── docs/                 # Comprehensive documentation
│   ├── security/         # Security architecture and policies
│   │   ├── SECURITY_ARCHITECTURE.md
│   │   ├── SECURITY_POLICY.md
│   │   └── INCIDENT_RESPONSE.md
│   ├── design/           # System design documentation
│   │   └── ARCHITECTURE.md
│   ├── roadmap/          # Product roadmap and strategy
│   │   └── ROADMAP.md
│   ├── product-log/      # Product documentation
│   │   └── PRODUCT_LOG.md
│   └── authcore-website/ # AuthCore showcase website
│       ├── index.html
│       ├── styles.css
│       ├── script.js
│       └── README.md
├── Makefile              # Build and development commands
└── .github/workflows/    # CI/CD workflows
    └── ci.yml

Enterprise Features

🏢 Enterprise Security

Multi-tenancy: Secure tenant isolation with namespace-based segmentation
Enterprise SSO: Integration with SAML, OIDC, and Active Directory
Compliance Automation: Automated compliance reporting and validation
Audit Logging: Comprehensive audit trails for all operations
Risk Management: Risk-based security policies and controls

📊 Observability and Monitoring

Prometheus Integration: Comprehensive metrics collection
Grafana Dashboards: Pre-built monitoring dashboards
Distributed Tracing: OpenTelemetry integration for request tracing
Alert Management: Intelligent alerting with reduced false positives
SLA Monitoring: Service level agreement tracking and reporting

🔧 Operations Excellence

GitOps Ready: Native GitOps workflow integration
Multi-cluster: Cross-cluster OpenFGA management
Disaster Recovery: Automated backup and recovery procedures
Performance Optimization: Intelligent resource allocation and scaling
Cost Management: Resource optimization and cost tracking

Roadmap and Releases

Current Release (v0.1.0-alpha) - Alpha Foundation ✅

Core operator functionality with security-first design
Advanced admission controller framework
Git commit verification and developer authentication
Malicious code injection analysis
Container image scanning and vulnerability assessment

Next Release (v0.2.0) - Enhanced Protection 🚧

AI-powered threat detection and behavioral analysis
Advanced incident response automation
Multi-tenancy support with enhanced isolation
Enterprise SSO integration
Advanced compliance reporting

Future Releases 📋

v0.3.0: Multi-cluster management and edge computing
v1.0.0: First stable release

For detailed roadmap information, see Product Roadmap.

Contributing

Security-First Development

All contributions must follow our security guidelines:

GPG Signed Commits: All commits must be signed with GPG keys
Security Review: Security review required for all PRs
Vulnerability Scanning: Automated scanning of all dependencies
Code Analysis: Static analysis for security vulnerabilities

Development Process

Fork the repository
Create a feature branch
Implement changes with security considerations
Run security checks: make security-check
Run tests: make test
Run all quality checks: make check-all
Submit a pull request with detailed security impact analysis

Security Contributions

We especially welcome contributions in:

Security architecture improvements
Threat detection enhancements
Compliance framework additions
Documentation and security guides

For security vulnerabilities, please follow our Security Policy and contact [email protected].

Support and Community

📞 Getting Help

Documentation: Complete documentation available
Issues: GitHub Issues for bug reports
Discussions: GitHub Discussions for questions
Security: [email protected] for security-related inquiries

🌟 Community

Star the Project: Show your support on GitHub
Join Discussions: Participate in community discussions
Contribute: Help improve the project through contributions
Share: Help others discover AuthCore and OpenFGA Operator

License and Open Source

This project is licensed under the Apache 2.0 License, ensuring:

Open Source: Fully open source with no vendor lock-in
Commercial Use: Free for commercial and enterprise use
Community Driven: Transparent development and governance
Extensible: Permissive license for modifications and integrations

See LICENSE for complete details.

Related Projects

OpenFGA - Fine-Grained Authorization system
kube-rs - Kubernetes client library for Rust

Name		Name	Last commit message	Last commit date
Latest commit History 227 Commits
.github		.github
crds		crds
demos		demos
docs		docs
examples		examples
issues		issues
kustomize		kustomize
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
ALPHA_USAGE.md		ALPHA_USAGE.md
CACHE_FALLBACK.md		CACHE_FALLBACK.md
CHAINGUARD-MIGRATION.md		CHAINGUARD-MIGRATION.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DEMOS.md		DEMOS.md
DEMO_QUICKSTART.md		DEMO_QUICKSTART.md
DOCKER_BUILD_OPTIMIZATION.md		DOCKER_BUILD_OPTIMIZATION.md
Dockerfile		Dockerfile
Makefile		Makefile
OPTIMIZATION_SUMMARY.md		OPTIMIZATION_SUMMARY.md
PODMAN.md		PODMAN.md
README.md		README.md
SCCACHE_FALLBACK_FIX.md		SCCACHE_FALLBACK_FIX.md
SECURITY.md		SECURITY.md
WORKFLOW_OPTIMIZATION.md		WORKFLOW_OPTIMIZATION.md
alpha-release-verification.sh		alpha-release-verification.sh
docker-compose.yml		docker-compose.yml

jralmaraz/authcore-openfga-operator

Folders and files

Latest commit

History

Repository files navigation