Middlewares

Middlewares process requests before they reach dispatchers and can modify responses on the way back. They’re used for cross-cutting concerns like authentication, rate limiting, and caching.

Overview

Middlewares are configured with x-barbacane-middlewares:

x-barbacane-middlewares:
  - name: <middleware-name>
    config:
      # middleware-specific config

Middleware Chain

Middlewares execute in order:

Request  →  [Global MW 1]  →  [Global MW 2]  →  [Operation MW]  →  Dispatcher
                                                                        │
Response ←  [Global MW 1]  ←  [Global MW 2]  ←  [Operation MW]  ←───────┘

Global vs Operation Middlewares

Global Middlewares

Apply to all operations:

openapi: "3.1.0"
info:
  title: My API
  version: "1.0.0"

# These apply to every operation
x-barbacane-middlewares:
  - name: request-id
    config:
      header: X-Request-ID
  - name: cors
    config:
      allowed_origins: ["https://app.example.com"]

paths:
  /users:
    get:
      # Inherits global middlewares
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Operation Middlewares

Apply to specific operations (run after global):

paths:
  /admin/users:
    get:
      x-barbacane-middlewares:
        - name: jwt-auth
          config:
            required: true
            scopes: ["admin:read"]
      x-barbacane-dispatch:
        name: http-upstream
        config:
          url: "https://api.example.com"

Merging with Global Middlewares

When an operation declares its own middlewares, they are merged with the global chain:

Global middlewares run first, in order
If an operation middleware has the same name as a global one, the operation config overrides that global entry
Non-overridden global middlewares are preserved

# Global: rate-limit at 100/min + cors
x-barbacane-middlewares:
  - name: rate-limit
    config:
      quota: 100
      window: 60
  - name: cors
    config:
      allow_origin: "*"

paths:
  /public/feed:
    get:
      # Override rate-limit, cors is still applied from globals
      x-barbacane-middlewares:
        - name: rate-limit
          config:
            quota: 1000
            window: 60
      # Resolved chain: cors (global) → rate-limit (operation override)

To explicitly disable all middlewares for an operation, use an empty array:

paths:
  /internal/health:
    get:
      x-barbacane-middlewares: []  # No middlewares at all

Consumer Identity Headers

All authentication middlewares set two standard headers on successful authentication, in addition to their plugin-specific headers:

Header	Description	Example
`x-auth-consumer`	Canonical consumer identifier	`"alice"`, `"user-123"`
`x-auth-consumer-groups`	Comma-separated group/role memberships	`"admin,editor"`, `"read"`

These standard headers enable downstream middlewares (like acl) to enforce authorization without coupling to a specific auth plugin.

Plugin	`x-auth-consumer` source	`x-auth-consumer-groups` source
`basic-auth`	username	`roles` array
`jwt-auth`	`sub` claim	configurable via `groups_claim`
`oidc-auth`	`sub` claim	`scope` claim (space→comma)
`oauth2-auth`	`sub` claim (fallback: `username`)	`scope` claim (space→comma)
`apikey-auth`	`id` field	`scopes` array

Authentication Middlewares

jwt-auth

Validates JWT tokens with RS256/HS256 signatures.

x-barbacane-middlewares:
  - name: jwt-auth
    config:
      issuer: "https://auth.example.com"  # Optional: validate iss claim
      audience: "my-api"                  # Optional: validate aud claim
      groups_claim: "roles"               # Optional: claim name for consumer groups
      skip_signature_validation: true     # Required until JWKS support is implemented

Accepted algorithms: RS256, RS384, RS512, ES256, ES384, ES512. HS256/HS512 and none are rejected.

Note: Cryptographic signature validation is not yet implemented. Set skip_signature_validation: true in production until JWKS support lands. Without it, all tokens are rejected with 401 at the signature step.

Property	Type	Default	Description
`issuer`	string	-	Expected `iss` claim. Tokens not matching are rejected
`audience`	string	-	Expected `aud` claim. Tokens not matching are rejected
`clock_skew_seconds`	integer	`60`	Tolerance in seconds for `exp`/`nbf` validation
`groups_claim`	string	-	Claim name to extract consumer groups from (e.g., `"roles"`, `"groups"`). Value is set as `x-auth-consumer-groups`
`skip_signature_validation`	boolean	`false`	Skip cryptographic signature check. Required until JWKS support is implemented

Property	Type	Default	Description
`key_location`	string	`header`	Where to find key (`header` or `query`)
`header_name`	string	`X-API-Key`	Header name (when `key_location: header`)
`query_param`	string	`api_key`	Query param name (when `key_location: query`)
`keys`	object	`{}`	Map of valid API keys to metadata

Property	Type	Default	Description
`introspection_endpoint`	string	required	RFC 7662 introspection URL
`client_id`	string	required	Client ID for introspection auth
`client_secret`	string	required	Client secret for introspection auth
`required_scopes`	string	-	Space-separated required scopes
`timeout`	float	`5.0`	Introspection request timeout (seconds)

Property	Type	Default	Description
`issuer_url`	string	required	OIDC issuer URL (e.g., `https://accounts.google.com`)
`audience`	string	-	Expected `aud` claim. If set, tokens must match
`required_scopes`	string	-	Space-separated required scopes
`issuer_override`	string	-	Override expected `iss` claim (for split-network setups like Docker)
`clock_skew_seconds`	integer	`60`	Clock skew tolerance for `exp`/`nbf` validation
`jwks_refresh_seconds`	integer	`300`	How often to refresh JWKS keys (seconds)
`timeout`	float	`5.0`	HTTP timeout for discovery and JWKS calls (seconds)
`allow_query_token`	boolean	`false`	Allow token extraction from the `access_token` query parameter (RFC 6750 §2.3). Use with caution — tokens in URLs risk leaking via logs and referer headers.

Keyboard shortcuts

Barbacane Documentation