Forward auth provider
type: forward_auth delegates the authentication decision to an external HTTP service (similar to
Traefik's ForwardAuth or NGINX auth_request). The gateway makes a sub-request to that service for
each request and maps its response to an authentication outcome.
How it works01
The provider issues an HTTP GET to
endpoint, copying each header named inforward_headersfrom the incoming request, and addingX-Original-URI(the request URI) andX-Original-Method(the request method).The auth service's response status decides the outcome:
2xx → Authenticated. The principal is read from response headers:
X-Auth-Subject(used as bothidandname),X-Auth-Role(comma-separated roles), andX-Auth-Scopes(comma-separated scopes). A missing subject defaults tounknown.401 → Unauthenticated.
Any other status, or a transport error reaching the service → Failed (with the status/body or error in the reason).
The principal is derived from the fixed response header names X-Auth-Subject,
X-Auth-Role, and X-Auth-Scopes. The response_headers configuration field is parsed but is
not currently used to copy arbitrary response headers back onto the upstream request — only
those three fixed headers shape the principal. The principal's id/roles/scopes are then re-emitted
upstream via the global auth.principal_header / roles_header / scopes_header.
Configuration02
| Key | Type | Default | Description |
endpoint | string | — | URL of the external auth service. The provider sends a GET here. Required. |
forward_headers | list of strings | ["Authorization", "Cookie", "X-Forwarded-For"] | Incoming headers copied onto the sub-request. |
response_headers | list of strings | ["X-Auth-Subject", "X-Auth-Role", "X-Auth-Scopes"] | Not wired — see callout above. |
timeout | duration | 5s | Timeout for the sub-request to the auth service. |
cache_ttl | duration | none | Not wired by this provider — see caching note. |
The sub-request is always a GET, with the original method and URI conveyed via the
X-Original-Method and X-Original-URI headers rather than by replaying the original request.
Caching note03
The forward-auth provider itself does not cache decisions; its cache_ttl field is not consumed.
However, the auth-gateway's shared token cache still applies when the request carries an
Authorization header (the cache key hashes the provider name plus that header), so repeated
requests with the same bearer token can be served from cache for auth.token_cache_ttl. Requests
authenticated by Cookie alone (no Authorization header and no TLS client CN) are not cached and
hit the auth service every time. See token caching.
Example04
auth_providers:
external-auth:
type: forward_auth
endpoint: http://auth-service.internal/verify
forward_headers: ["Authorization", "Cookie", "X-Forwarded-For"]
timeout: 2s
auth:
default_provider: external-auth
global_enforce: trueYour auth service should return 2xx with X-Auth-Subject (and optionally X-Auth-Role /
X-Auth-Scopes) for an authenticated caller, 401 for an unauthenticated one, and any other
status to signal an error.