Forward Auth Configuration
Configuration reference for the Forward Auth plugin (`forward-auth`): the parameters, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
uri — string · required · since APISIX 2.12.0
URI of the external authorization service.
ssl_verify — boolean · optional · default: true · since APISIX 2.12.0
If true, verify the authorization service's SSL certificate.
request_method — string · optional · default: GET · since APISIX 2.14.1
Valid values: GET or POST
HTTP 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 the extra_headers field. 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 — integer · optional · default: 67108864 · min: 1 · since APISIX 3.17.0 · API7 Gateway 3.9.14
Maximum request body size in bytes that is buffered and forwarded to the external authorization service when request_method is POST (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 — array[string] · optional · default: [] · since APISIX 2.12.0
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 — array[string] · optional · default: [] · since APISIX 2.12.0
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 — array[string] · optional · default: [] · since APISIX 2.12.0
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 — object · optional · since APISIX 3.14.0 · API7 Gateway 3.8.7
Additional headers to send to the authorization service. Support built-in variables (opens in Apache APISIX docs) in values.
timeout — integer · optional · default: 3000 · since APISIX 2.12.0
Valid values: between 1 and 60000 inclusive
Timeout for the external authorization service HTTP call in milliseconds.
keepalive — boolean · optional · default: true · since APISIX 2.12.0
If true, keep the connections open for multiple requests.
keepalive_timeout — integer · optional · default: 60000 · since APISIX 2.12.0
Valid values: greater than or equal to 1000
Idle time after which the established HTTP connections will be closed.
keepalive_pool — integer · optional · default: 5 · since APISIX 2.12.0
Valid values: greater than or equal to 1
Maximum number of connections in the connection pool.
allow_degradation — boolean · optional · default: false · since APISIX 3.4.0
If true, allow APISIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
status_on_error — integer · optional · default: 403 · since APISIX 3.9.0
Valid values: between 200 and 599 inclusive
HTTP status code to return to the client when there is a network error with the external authorization service.