Authentication & authorization

This page is the configuration reference for the auth_providers, auth, and cors sections. For the request flow and conceptual depth, see the Security section.

Authentication providers are declared once under auth_providers (a map keyed by provider name) and referenced by name from the global auth block or from a route's auth_provider field. A single auth-gateway middleware enforces both authentication and authorization; it is enabled when any provider is defined or when auth.global_enforce is true.

auth_providers:
  primary-jwt:
    type: jwt
    secret: "${JWT_SECRET}"
    algorithm: HS256
    issuer: https://auth.example.com

auth:
  default_provider: primary-jwt
  global_enforce: true
  skip_paths: ["/health", "/public/*"]
  authz:
    engine: rhai

Auth providers01

auth_providers is a map from provider name to a provider definition. Each definition is tagged by a type field (jwt, oidc, api_key, forward_auth, or mtls).

yaml

auth_providers:
  primary-jwt:
    type: jwt
    secret: "${JWT_SECRET}"
    algorithm: HS256
    issuer: https://auth.example.com
    audience: my-api

auth_providers:
  external:
    type: forward_auth
    endpoint: http://authsvc:9000/verify
    forward_headers: [Authorization, Cookie, X-Forwarded-For]
    response_headers: [X-Auth-Subject, X-Auth-Role, X-Auth-Scopes]
    timeout: 5s
    cache_ttl: 30s

`auth`02

Global authentication settings. All fields have defaults, so the whole block is optional.

auth:
  default_provider: primary-jwt
  global_enforce: true
  skip_paths: ["/health", "/public/*"]
  token_cache_ttl: 60s
  error_format: json

Key	Type	Default	Description
`default_provider`	string	none	Provider applied to routes without an explicit `auth_provider`.
`global_enforce`	boolean	`false`	Require auth on all routes unless `skip_auth` or matched by `skip_paths`.
`skip_paths`	array of string	`[]`	Paths exempt from authentication (supports wildcards).
`principal_header`	string	`X-Auth-Principal`	Header injected with the authenticated principal ID.
`roles_header`	string	`X-Auth-Roles`	Header injected with the principal's roles.
`scopes_header`	string	`X-Auth-Scopes`	Header injected with the authenticated scopes.
`token_cache_ttl`	duration	`60s`	Cache validated tokens for this duration.
`error_format`	string	`json`	Error response format: `json` or `text`.
`authz`	object	Rhai engine	Authorization settings. See below.

Authz03

auth.authz selects the authorization engine and holds global rules.

auth:
  authz:
    engine: both
    global_rules:
      - name: deny-internal
        rule: 'request.path.starts_with("/internal")'
        action: deny
    opa:
      endpoint: http://opa:8181/v1/data/octopus/allow
      timeout: 100ms
      cache_ttl: 5m
      fail_open: false

Key	Type	Default	Description
`engine`	string	`rhai`	Authorization engine: `rhai`, `opa`, or `both`.
`global_rules`	array	`[]`	Rules applied to all authenticated requests. See below.
`opa`	object	none	OPA integration settings. See below.

global_rules[] entries (AuthzRule):

Key	Type	Default	Description
`name`	string	—	Rule name. Required.
`description`	string	none	Optional description.
`engine`	string	inherits	Override engine for this rule (`rhai`, `opa`, or `both`).
`rule`	string	—	Rhai expression or OPA policy path. Required.
`action`	string	`allow`	Action when the rule matches: `allow` or `deny`.

opa object (OpaConfig):

Key	Type	Default	Description
`endpoint`	string	—	OPA REST API endpoint. Required.
`timeout`	duration	`100ms`	Request timeout.
`cache_ttl`	duration	`5m`	Cache OPA decisions for this duration.
`fail_open`	boolean	`false`	Allow the request if OPA is unreachable.

Global CORS04

The top-level cors section sets a global CORS policy. Individual routes can override it with routes[].cors (see Routes).

cors:
  allowed_origins: ["https://app.example.com"]
  allowed_methods: [GET, POST, PUT, DELETE, OPTIONS]
  allowed_headers: [Authorization, Content-Type]
  exposed_headers: [X-Request-Id]
  max_age: 3600
  allow_credentials: true

Key	Type	Default	Description
`allowed_origins`	array of string	`[]`	Permitted origins (use `["*"]` with care).
`allowed_methods`	array of string	`[GET, POST, PUT, DELETE, OPTIONS]`	Permitted HTTP methods.
`allowed_headers`	array of string	`[]`	Permitted request headers.
`exposed_headers`	array of string	`[]`	Response headers exposed to the browser.
`max_age`	integer (seconds)	`3600`	Preflight cache max age.
`allow_credentials`	boolean	`false`	Allow credentials (cookies, auth headers).

Note

Authorization rules use the embedded Rhai engine, an external OPA service, or both. See Security for guidance on writing rules and policies.

← Previous

Middleware

FARP & discovery

Authentication & authorization

Authentication & authorization

Auth providers01

auth02

Authz03

Global CORS04

Got somethinghard to build?

`auth`02

Got something
hard to build?