Skip to main content

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:

Add the required overrides to the persistent gateway configuration:

config.yaml
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.

Use the Lua client only if the authorization service depends on one of these client-specific behaviors:

BehaviorNative clientLua client
Connection header (not controlled by keepalive)Sends Connection: keep-aliveDoes not add the header
Empty GET requestSends Content-Length: 0Does not add the header
Default User-AgentDoes not add the headerSends a lua-resty-http user agent
Response-read timeoutApplies one timeout to the complete responseApplies 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

    string

    required


    URI of the external authorization service.

  • ssl_verify

    boolean

    default: true


    If true, verify the authorization service's SSL certificate.

  • request_method

    string

    default: GET

    vaild vaule:

    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

    default: 67108864


    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]

    default: []


    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]

    default: []


    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]

    default: []


    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


    Additional headers to send to the authorization service. Support built-in variables in values.

  • timeout

    integer

    default: 3000

    vaild vaule:

    between 1 and 60000 inclusive


    Timeout for the external authorization service HTTP call in milliseconds.

  • keepalive

    boolean

    default: true


    If true, keep the connections open for multiple requests.

  • keepalive_timeout

    integer

    default: 60000

    vaild vaule:

    greater than or equal to 1000


    Idle time after which the established HTTP connections will be closed.

  • keepalive_pool

    integer

    default: 5

    vaild vaule:

    greater than or equal to 1


    Maximum number of connections in the connection pool.

  • allow_degradation

    boolean

    default: false


    If true, allow APISIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable.

  • status_on_error

    integer

    default: 403

    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.