Forward Auth Configuration
The forward-auth plugin integrates with external authorization services, enhancing API security and access control. Configuration covers static settings and plugin parameters.
Static Configurations
Two gateway-level settings affect Forward Auth. http_client selects the client used to call the authorization service. apisix.max_request_headers_readable controls how many client request headers are available for request_headers forwarding.
Both settings are available in APISIX 3.20.0 and API7 Enterprise 3.10.10. Earlier versions do not expose http_client and use a fixed request-header limit of 100.
The examples show both settings together. Include only the overrides you need in the file for your deployment:
- Host or Docker
- API7 Gateway Helm
Add the required overrides to the persistent gateway configuration:
apisix:
max_request_headers_readable: 200 # Default: 100; 0 reads all request headers.
plugin_attr:
forward-auth:
http_client: lua-resty-http # Default native client: ngx_http_ffi_client
Reload or restart every gateway instance after updating config.yaml.
The maxRequestHeadersReadable value requires API7 Gateway Helm chart 3.10.19 or later. Add the required overrides to the complete values file used by the gateway release:
apisix:
maxRequestHeadersReadable: 200 # Default: 100; 0 reads all request headers.
pluginAttrs:
forward-auth:
http_client: lua-resty-http # Default native client: ngx_http_ffi_client
Apply the complete values file through the gateway release's normal Helm upgrade workflow.
Use the Lua client only if the authorization service depends on one of these client-specific behaviors:
| Behavior | Native client | Lua client |
|---|---|---|
Connection header (not controlled by keepalive) | Sends Connection: keep-alive | Does not add the header |
Empty GET request | Sends Content-Length: 0 | Does not add the header |
Default User-Agent | Does not add the header | Sends a lua-resty-http user agent |
| Response-read timeout | Applies one timeout to the complete response | Applies the timeout to each receive operation |
The request-header setting only changes the header table visible to plugins. It does not change NGINX parsing limits; headers beyond the plugin-visible limit can still reach the upstream.
Parameters
See plugin common configurations for configuration options available to all plugins.
uri
URI of the external authorization service.
ssl_verify
If true, verify the authorization service's SSL certificate.
request_method
vaild vaule:
GETorPOSTHTTP method APISIX uses to send requests to the external authorization service. By default, APISIX sends GET requests to the external authorization service.
When set to
POST, APISIX will send POST requests along with the request body to the external authorization service. This is, however, not recommended. If the authorization decision depends on request parameters from a POST body, it is recommended to extract the necessary fields using$post_arg.*and pass them via theextra_headersfield. This approach avoids sending the full request body, reduces overhead, and keeps the authorization service focused on headers for decision-making.max_req_body_size
Maximum request body size in bytes that is buffered and forwarded to the external authorization service when
request_methodisPOST(default 67108864 bytes, which is 64 MB). Requests with a body larger than this limit are rejected with HTTP 413. Available in API7 Enterprise from version 3.9.14 and APISIX from version 3.17.0.request_headers
Client request headers that should be forwarded to the external authorization service. If not configured, only headers added by APISIX are forwarded, such as
X-Forwarded-*.upstream_headers
External authorization response headers controlled by the plugin before the request is forwarded upstream. The gateway forwards a configured header when the authorization service returns it and clears any client-supplied value when the authorization response omits it. If not configured, no authorization response headers are forwarded.
client_headers
External authorization service response headers that should be forwarded to the client when authentication fails. If not configured, no headers are forwarded to the client.
extra_headers
Additional headers to send to the authorization service. Support built-in variables in values.
timeout
vaild vaule:
between 1 and 60000 inclusive
Timeout for the external authorization service HTTP call in milliseconds.
keepalive
If true, keep the connections open for multiple requests.
keepalive_timeout
vaild vaule:
greater than or equal to 1000
Idle time after which the established HTTP connections will be closed.
keepalive_pool
vaild vaule:
greater than or equal to 1
Maximum number of connections in the connection pool.
allow_degradation
If true, allow APISIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
status_on_error
vaild vaule:
between 200 and 599 inclusive
HTTP status code to return to the client when there is a network error with the external authorization service.