Files

Björn Benouarets 78da787f43 feat(auth): Add authentication middleware

2026-02-06 00:08:27 +01:00

7.5 KiB

Raw Blame History

Configuration

The gateway is configured via a single YAML file (gateway.yaml). This document describes all available configuration options.

Configuration File Structure

gateway:
  host: "0.0.0.0"
  port: 8080
  features:
    - request_id
    - real_ip
    - logger
    - host

hosts:
  - id: "host-001"
    name: "localhost"
    domain: "localhost:8080"

targets:
  - id: "target-001"
    name: "httpbin"
    url: "https://httpbin.org"

apis:
  - id: "api-001"
    host: "host-001"
    target: "target-001"

routes:
  - id: "route-001"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        type: "api_key"
        header: "X-Api-Key"
        path:
          include: []
          exclude: []

Sections

Gateway

Global gateway configuration.

Field	Type	Description	Default
`host`	string	Host address to bind to	Required
`port`	integer	Port number	Required
`features`	array	Global middleware features	Required

Features

Available global features:

Feature	Description
`request_id`	Adds unique request ID to each request
`real_ip`	Determines real client IP from headers
`logger`	Logs all HTTP requests with structured JSON
`host`	Logs the host header for each request

Hosts

Virtual hosting configuration for domain-based routing.

Field	Type	Description
`id`	string	Unique host identifier (referenced by APIs)
`name`	string	Human-readable name
`domain`	string	Domain/host name to match

Targets

Backend service definitions referenced by APIs.

Field	Type	Description
`id`	string	Unique target identifier (referenced by APIs)
`name`	string	Human-readable name
`url`	string	Backend URL to proxy to

APIs

Links hosts to backend targets.

Field	Type	Description
`id`	string	Unique API identifier (referenced by routes)
`host`	string	Host ID to use
`target`	string	Target ID to proxy to

Routes

Route definitions with path patterns, prefix stripping, and authentication.

Field	Type	Description
`id`	string	Unique route identifier
`api`	string	API ID to use for this route
`path`	string	Chi route pattern (e.g., `/api/v1/*`)
`strip_prefix`	object	Prefix stripping configuration
`security`	object	Security policies (auth)

Strip Prefix

Field	Type	Description
`enabled`	boolean	Enable prefix stripping
`prefix`	string	Prefix to remove from path

Security

Authentication

Field	Type	Description
`enabled`	boolean	Enable authentication
`type`	string	Auth type identifier (for documentation)
`header`	string	Header name to validate (e.g., `X-Api-Key`, `Authorization`)
`path`	object	Path-based filtering configuration

Auth Path Filtering

Field	Type	Description
`include`	array	Paths that require auth (empty = all, if set only these)
`exclude`	array	Paths that skip auth (only used if include is empty)

Path Filtering Logic:

Include	Exclude	Behavior
Empty	Empty	Auth required for ALL paths
Set	Empty	Auth required ONLY for paths matching include
Empty	Set	Auth required for ALL EXCEPT paths matching exclude
Set	Set	Include takes precedence (same as "Set, Empty")

Wildcards in Path Patterns:

* matches any path
/api/* matches /api/ and any subpath
/api/v1/public/test/* matches the prefix and any subpath

Example Configurations

Public API (No Auth)

routes:
  - id: "public-api"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false

Protected API (All Paths Require Auth)

routes:
  - id: "protected-api"
    api: "api-001"
    path: "/api/v1/*"
    strip_prefix:
      enabled: true
      prefix: "/api/v1"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: []

Public with Protected Sub-paths (Include)

routes:
  - id: "mixed-api"
    api: "api-001"
    path: "/api/*"
    strip_prefix:
      enabled: true
      prefix: "/api"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: ["/api/admin/*", "/api/users/*/profile"]
          exclude: []

In this example:

/api/admin/users → Requires auth (matches include)
/api/users/123/profile → Requires auth (matches include)
/api/public/data → No auth (doesn't match include)
/api/health → No auth (doesn't match include)

Protected with Public Sub-paths (Exclude)

routes:
  - id: "protected-with-public"
    api: "api-001"
    path: "/api/*"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: ["/api/health", "/api/public/*", "/api/v1/public/test/*"]

In this example:

/api/health → No auth (matches exclude)
/api/public/data → No auth (matches exclude)
/api/v1/public/test/123 → No auth (matches exclude)
/api/users → Requires auth (doesn't match exclude)
/api/admin/settings → Requires auth (doesn't match exclude)

Multiple Routes with Different Auth

routes:
  - id: "public-route"
    api: "api-001"
    path: "/public/*"
    strip_prefix:
      enabled: true
      prefix: "/public"
    security:
      auth:
        enabled: false

  - id: "user-route"
    api: "api-001"
    path: "/users/*"
    strip_prefix:
      enabled: true
      prefix: "/users"
    security:
      auth:
        enabled: true
        header: "X-Api-Key"
        path:
          include: []
          exclude: ["/users/login", "/users/register"]

  - id: "admin-route"
    api: "api-001"
    path: "/admin/*"
    strip_prefix:
      enabled: true
      prefix: "/admin"
    security:
      auth:
        enabled: true
        header: "Authorization"
        path:
          include: []
          exclude: []

Configuration Loading

The gateway loads configuration from a file path relative to the binary:

cfg, err := config.NewFile("../gateway.yaml")

For Docker deployments, mount the config file:

volumes:
  - ./gateway.yaml:/app/gateway.yaml:ro

Chi Route Patterns

The gateway uses chi/v5 routing patterns. Common patterns:

Pattern	Matches	Example
`/api/*`	`/api/` and any subpath	`/api/users`, `/api/users/123`
`/api/v1/*`	`/api/v1/` and any subpath	`/api/v1/users`
`/users/{id}`	`/users/` with any value	`/users/123`
`/files/*`	`/files/` and any subpath	`/files/doc.pdf`

Note: /* matches zero or more path segments.

Debug Logging

To see detailed authentication decisions, enable DEBUG logging in main.go:

masterlog.SetLevel(masterlog.LevelDebug)

This will output logs like:

{
  "level": "debug",
  "msg": "AuthMiddleware: Checking if path requires auth",
  "path": "/api/v1/users",
  "requires_auth": true,
  "include": [],
  "exclude": ["/api/v1/public/*"]
}

7.5 KiB Raw Blame History