protoc-gen-authz

A Buf/protoc plugin that generates authorization permission mappings for gRPC services.

Overview

This plugin extracts authorization permission metadata from your protobuf service definitions and generates a Go map that links RPC procedures to their required permissions.

Installation

Option 1: Download Pre-built Binary

Download the latest release for your platform from the releases page.

Quick install script:

curl -fsSL https://raw.githubusercontent.com/rimdesk/protoc-gen-authz/main/install.sh | bash

Or specify a version:

curl -fsSL https://raw.githubusercontent.com/rimdesk/protoc-gen-authz/main/install.sh | bash -s v1.0.0

Manual installation:

# macOS (Apple Silicon)
curl -L https://github.com/rimdesk/protoc-gen-authz/releases/latest/download/protoc-gen-authz-darwin-arm64 -o protoc-gen-authz
chmod +x protoc-gen-authz
sudo mv protoc-gen-authz /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/rimdesk/protoc-gen-authz/releases/latest/download/protoc-gen-authz-darwin-amd64 -o protoc-gen-authz
chmod +x protoc-gen-authz
sudo mv protoc-gen-authz /usr/local/bin/

# Linux (ARM)
curl -L https://github.com/rimdesk/protoc-gen-authz/releases/latest/download/protoc-gen-authz-linux-arm64 -o protoc-gen-authz
chmod +x protoc-gen-authz
sudo mv protoc-gen-authz /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/rimdesk/protoc-gen-authz/releases/latest/download/protoc-gen-authz-linux-amd64 -o protoc-gen-authz
chmod +x protoc-gen-authz
sudo mv protoc-gen-authz /usr/local/bin/

Option 2: Install with Go

If you have Go installed:

go install github.com/rimdesk/protoc-gen-authz@latest

Usage

Add to your buf.gen.yaml:

version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen
    opt: paths=source_relative
  - remote: buf.build/connectrpc/go
    out: gen
    opt: paths=source_relative
  - local: protoc-gen-authz
    out: gen
    opt: paths=source_relative

Then run:

buf generate

Proto Definition

In your .proto files, annotate your RPC methods with permission metadata:

syntax = "proto3";

package warehouse.v1;

import "rimdesk/common/v1/authz.proto";

service WarehouseService {
  rpc CreateWarehouse(CreateWarehouseRequest) returns (CreateWarehouseResponse) {
    option (rimdesk.common.v1.permission) = "warehouse:warehouse:create";
  }
  
  rpc GetWarehouse(GetWarehouseRequest) returns (GetWarehouseResponse) {
    option (rimdesk.common.v1.permission) = "warehouse:warehouse:read";
  }
}

Generated Output

The plugin generates a .authz.pb.go file with a Permissions map:

package warehousev1

type Permission struct {
    Domain   string
    Resource string
    Action   string
}

var Permissions = map[string]Permission{
    "/warehouse.v1.WarehouseService/CreateWarehouse": {
        Domain:   "warehouse",
        Resource: "warehouse",
        Action:   "create",
    },
    "/warehouse.v1.WarehouseService/GetWarehouse": {
        Domain:   "warehouse",
        Resource: "warehouse",
        Action:   "read",
    },
}

Using the Generated Permissions

You can use the generated permissions map in your authorization middleware:

import warehousev1 "github.com/rimdesk/warehouse-api/gen/rimdesk/warehouse/v1"

func AuthzInterceptor(procedure string, userPermissions []Permission) error {
    required, ok := warehousev1.Permissions[procedure]
    if !ok {
        return errors.New("unknown procedure")
    }
    
    // Check if user has the required permission
    if !hasPermission(userPermissions, required) {
        return errors.New("permission denied")
    }
    
    return nil
}

Permission Format

Permissions must follow the format: domain:resource:action

• domain: The service domain (e.g., "warehouse", "user", "inventory")
• resource: The specific resource type (e.g., "warehouse", "product", "order")
• action: The operation being performed (e.g., "create", "read", "update", "delete")

Development

Building from source

git clone https://github.com/rimdesk/protoc-gen-authz.git
cd protoc-gen-authz
make build

Running tests

go test ./...

Creating a release

# Create and push a tag
make tag VERSION=v1.0.0

# Or manually
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

GitHub Actions will automatically build and publish the release.

License

Apache License 2.0