RHOBS Auth Gateway

RHOBS Auth Gateway is a Go library that loads one YAML configuration and generates Envoy files or Kubernetes resources. It does not run Envoy or a controller.

The supported features include exact-host routing, HTTP and HTTPS listeners, HTTP/1 and HTTP/2 upstreams, JWT, API-key, and client-certificate mTLS authentication, attribute-based authorization, request header forwarding, per-API response counters, opt-in per-API fault injection, access logs, Prometheus metrics, and OpenTelemetry traces.

Requirements

Importing this module requires Go 1.26 or later. The module is pre-v1.0 and does not promise a stable Go API. The YAML schema accepts only version: 1; the loader rejects unknown fields and extra YAML documents and does not migrate older formats.

Generate configuration

Install the module:

go get github.com/rhobs/auth-gateway

The public configuration structs live in pkg/api/types.go. pkg/gateway loads and validates the API and generates Envoy files, Kubernetes resources, and collector configuration. Feature code and unit tests share matching file names, with one fixture tree under pkg/gateway/testdata.

Load and generate files or a Kubernetes manifest from Go:

package main

import (
	"fmt"
	"log"
	"strings"

	"github.com/rhobs/auth-gateway/pkg/gateway"
)

func main() {
	cfg, err := gateway.Load(strings.NewReader(`version: 1
servers:
  - hostname: status.example.com
    apis:
      - name: status
        public: true
apis:
  - name: status
    upstream: {address: httpbin, port: 8080}
    routes:
      - methods: [GET]
        path: {exact: /status}
kubernetes:
  name: auth-gateway
  namespace: observability
`))
	if err != nil {
		log.Fatal(err)
	}

	files, err := gateway.Generate(cfg)
	if err != nil {
		log.Fatal(err)
	}
	resources, err := gateway.GenerateKubernetes(cfg)
	if err != nil {
		log.Fatal(err)
	}
	manifest, err := resources.YAML()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(files.EnvoyBootstrap.Path)
	fmt.Print(string(manifest))
}

gateway.Generate returns Envoy files with their required paths. It does not need Kubernetes settings. gateway.GenerateKubernetes requires a kubernetes section and returns typed resources. Neither call contacts a cluster or creates the referenced namespace, TLS Secrets, API-key Secret, or CA ConfigMaps. Create those resources first, then apply the manifest.

The full configuration example covers the supported schema and comments optional settings and defaults. The configuration reference lists every field, default, and validation rule. Empty Kubernetes image values use the pinned Go defaults documented there; set image fields to use approved images or mirrors.

For file-based API-key deployments, omit api_key.secret and provide the separate API-key ECDS file. mTLS deployments must provide the configured client CA bundle. See the API-key guide for the credential format and the mTLS guide for client certificate setup.

Gateway behavior

Each server binds one exact hostname to an ordered list of APIs. API routes use an exact path, prefix, or regular expression. A matching path with an unsupported method returns 405; an unknown host or path returns 404. HTTPS uses SNI to select a certificate and then checks the request host.

Each server/API binding explicitly selects public access or protected entries. Original request headers select one tenant access entry; that entry selects JWT or API-key authentication and grants tied to the verifying authenticator. JWT entries can trust multiple providers. Optional attribute equality binds a requested tenant header to a verified credential value. mTLS uses dedicated HTTPS servers with mandatory client certificates and no API-level authentication. Unmatched or unauthorized requests are denied before the backend. APIs can also declare fixed attributes for all their matched routes, including public routes. Routes forward source attributes to upstream headers, and metrics use the same source values. Supply an additional source attribute when an upstream needs a different value. See the JWT guide, API-key guide, mTLS guide, and Envoy behavior guide for request and update behavior.

For SLO tests, an API can inject HTTP errors after authentication and authorization, optionally matching a request header and authenticated tenant. The policy is off by default and requires an explicit gateway rollout. Injected replies count as standard requests in the per-API counter, using the same status and attribute labels as backend replies. See the fault injection guide.

API-key changes update the Secret. Downstream certificate and client CA ConfigMap changes reload through SDS for new connections. Static Envoy configuration changes require an explicit Deployment rollout; the generated Deployment has no checksum annotation.

Local playground

The Docker Compose demo exercises public, JWT, API-key, and tenant-selected access with mock OAuth, httpbin, metrics, and traces. Start with playground/README.md.

Development and contributions

Develop feature changes on a branch and submit them to the upstream repository through a pull request for review. See CONTRIBUTING.md for the contribution workflow, checks, and golden-file updates.

License

This project is licensed under the Apache License 2.0. See LICENSE.