authorization-service

Authorization Service

A production-grade gRPC and REST API service for managing authorization and permissions in a microservices architecture. Built with Go 1.25, leveraging OpenFGA for fine-grained authorization, Valkey for caching, and PostgreSQL for persistent queue-based permission-update operations.

Overview

The Authorization Service (codename Cerberus) is designed to provide:

1. Permission Management: Register and manage service permissions via a versioned gRPC API
2. Authorization Decisions: Perform authorization decisions using OpenFGA
3. Envoy Integration: Implements Envoy's standard External Authorization API (v3) for use with Istio or other service meshes
4. Caching: Uses Valkey for high-performance authorization decision caching
5. Ingestion Pipeline: Highly scalable, async Kafka-based permission-update event ingestion
6. Token Validation: Integrates with the Secure Token Service (STS) for token validation

Architecture

graph TB
    subgraph clients["Clients"]
        A["Microservices"]
        B["Envoy/Istio"]
        C["External Apps"]
    end
    subgraph authz["Authorization Service"]
        REST["REST API Gateway<br/>:8070"]
        GRPC["gRPC Server<br/>:9091"]
        PERMS["Permissions<br/>Service"]
        AUTHZ["Authorization<br/>Service"]
        REST -->|Transcode| GRPC
        GRPC --> PERMS
        GRPC -->|External AuthZ| AUTHZ
    end
    subgraph integrations["Integrations"]
        FGA["OpenFGA<br/>Fine-Grained<br/>Authorization"]
        VALKEY["Valkey<br/>Cache"]
        STS["Secure Token<br/>Service"]
        POSTGRES["Postgres DB<br/>Queue/State"]
        KAFKA["Kafka Broker"]
    end
    subgraph external["External Services"]
        ISTIO["Istio Service Mesh"]
    end
    A -->|Register Permissions| GRPC
    B -->|External AuthZ Check| GRPC
    C -->|REST Health Checks| REST
    PERMS --> VALKEY
    AUTHZ --> FGA
    AUTHZ --> VALKEY
    AUTHZ --> STS
    ISTIO -->|Authorization Requests| GRPC
    KAFKA -->|Permission Updates| GRPC
    POSTGRES -->|Durability Queue| GRPC

Features

• Cobra CLI: Professional command-line interface with automatic help generation and dedicated subcommands
• Versioned gRPC APIs with Go code generation from protobuf definitions
• REST API Gateway using grpc-gateway for transcoding gRPC to REST (currently exposes health endpoints)
• OpenFGA Integration: Fine-grained, relationship-based access control
• Valkey Caching: Cache authorization decisions for ultra-low latency check responses
• Database Durability: PostgreSQL-backed transactional queue for robust, horizontally scalable ingestion
• Kafka-Based Ingestion: Listeners that consume permission changes asynchronously from federated services
• Graceful Shutdown: Strict connection cleanup and signal handling

Prerequisites

• Go: 1.25 or later
• Docker: For running dependencies
• Docker Compose: For orchestrating containers

Installation & Setup

1. Clone the Repository

git clone https://github.com/canonical/authorization-service.git
cd authorization-service

2. Install Dependencies

go mod download
go mod tidy

3. Build the Service

make build

This creates bin/app binary.

Running the Service

Quick Start (Recommended)

# Start Docker dependencies (Postgres, Kafka, Valkey, OpenFGA, STS)
make start-deps

# Run the service (in another terminal)
./bin/app serve

Development Mode

Builds, starts dependencies, and runs with debug logging:

make dev

Using Make

make build        # Build binary (bin/app)
make run          # Run service
make start-deps   # Start docker dependencies
make stop-deps    # Stop docker dependencies
make test         # Run unit tests
make test-int     # Run integration tests
make coverage     # Generate HTML coverage report

CLI Commands

The service uses Cobra to expose multiple operational subcommands:

serve - Start the Service

./bin/app serve

Starts both the gRPC server (default port 9091) and the REST gateway (default port 8070).

migrate - Run Database Migrations

./bin/app migrate --dsn "postgres://authz:authz-password@localhost:5432/cerberus?sslmode=disable" up

Runs schema migrations against the PostgreSQL database. Supports up, down [version], and status actions.

listen - Start Kafka Listener

./bin/app listen

Starts the Kafka permission-update listener which consumes permission events from federated services' <slug>.permissions topics and persists them into the PostgreSQL work queue.

worker - Start Async Permission Worker

./bin/app worker

Starts the background worker that polls the PostgreSQL work queue and applies the pending permission changes to OpenFGA.

reaper - One-off Stale-Row Reaper

./bin/app reaper

Scans the work queue for processing jobs that have timed out and returns them to the queue to be retried.

ensure-topics - Idempotently Create Kafka Topics

./bin/app ensure-topics

Creates the <slug>.permissions Kafka topic for every federated service listed in the FEDERATED_SERVICES configuration. Existing topics are left untouched, making this command safe to run repeatedly.

seed - Seeding & Validation of Route Rules

Handles loading, verifying, and seeding versioned rules.yaml routing rules:

./bin/app seed

Seeds embedded rules into the PostgreSQL database. Compares and replaces revisions atomically.

• validate Subcommand: Validates route rules syntax and structure without requiring an active database or environment variables:

  # Validate default embedded rules
  ./bin/app seed validate
  
  # Validate rules under a custom directory
  ./bin/app seed validate --dir path/to/services
  

• Dry-Run Mode: You can also perform the same config-independent validation using the dry-run flag:

  ./bin/app seed --dry-run
  

authz - Authorization Model Management

Provides utilities for checking permissions and writing models to OpenFGA directly:

• check Subcommand: Simulates an Envoy External Authorization Check request using a session cookie to test STS integration:

  ./bin/app authz check --cookie "session=abc123xyz" --path "/api/resource" --method "GET"
  

• write-model Subcommand: Compiles the modular authorization model from the embedded manifest and writes it to the specified OpenFGA store:

  ./bin/app authz write-model <store-id>
  

version - Show Version

./bin/app version

Configuration

Configuration is managed through Viper, providing a robust, multi-layered system. Configuration can be passed via:

1. Cobra CLI Flags (highest priority)
2. Environment Variables (nested paths mapped to structured uppercase words)
3. YAML Config File (loaded from ./cerberus.yaml, /etc/authz/cerberus.yaml, or specified with -c / --config)
4. Go-defined Defaults (lowest priority)

To view or start with a baseline YAML configuration, refer to the provided cerberus.yaml.example file.

CLI Configuration Flags

The following flags are available globally across all CLI commands to quickly override settings:

• -c, --config <path>: Path to a custom YAML configuration file.
• --grpc-port <int>: Overrides the gRPC server port.
• --http-port <int>: Overrides the HTTP API Gateway port.
• --server-host <string>: Overrides the server bind host address.
• --db-host <string>: Overrides the PostgreSQL database host.
• --db-port <int>: Overrides the PostgreSQL database port.
• --db-name <string>: Overrides the PostgreSQL database name.
• --db-user <string>: Overrides the PostgreSQL database user.
• --dev: Enables development mode.
• --log-level <string>: Overrides the logging level.
• --log-format <string>: Overrides the logging format (json or text).
• --fga-address <string>: Overrides the OpenFGA server address.
• --fga-store-id <string>: Overrides the OpenFGA Store ID.
• --fga-model-id <string>: Overrides the OpenFGA Authorization Model ID.

Structured Environment Variables & YAML Keys

Server Configuration

External Authz Service Configuration

OpenFGA Configuration

Valkey Configuration

Postgres Configuration

STS Configuration

Kafka Configuration

Worker Configuration

Logging Configuration

Telemetry Configuration

Running Tests

Unit Tests

make test

Integration Tests

Requires running Docker environment:

make test-int

Coverage Report

Generates code coverage maps:

make coverage

View the results by opening coverage.html in your browser.

API Endpoints

gRPC Service Endpoints (Port 9091)

• Permissions Management Service: authorization.service.api.v1.PermissionsService
  • RegisterPermissions
  • GetPermissions
  • ListPermissions
  • DeletePermissions
• Envoy External Authorization: envoy.service.auth.v3.Authorization
  • Check

REST Gateway Endpoints (Port 8070)

• GET /healthz - Liveness/readiness health check Note: The /v1/permissions routes are defined in proto definitions but are currently comment-disabled in gateway.go and require direct gRPC client calls.

Service Federation

Service onboarding and federation into Cerberus are managed through a dedicated pull request workflow, treating the PR as the primary source of truth for configuration and metadata.

If you are a team onboarding your service, you can open your pull request with the dedicated federation template pre-loaded by clicking the button below:

Alternatively, you can manually select the federation_onboarding.md template when opening your Pull Request.

Contributing

See CONTRIBUTING.md for guidelines.

License

See LICENSE file for details.