# 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[​](#static-configurations "Direct link to 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:

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`.

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:

values.yaml

```
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[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) 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`

  valid value:

  `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](https://docs.api7.ai/apisix/reference/built-in-variables.md) in values.

* timeout

  integer

  default: `3000`

  valid value:

  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`

  valid value:

  greater than or equal to 1000

  ***

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

* keepalive\_pool

  integer

  default: `5`

  valid value:

  greater than or equal to 1

  ***

  Maximum number of idle connections retained in a keepalive pool per NGINX worker process. Workers and gateway instances do not share these pools.

  For one pool, four workers with `keepalive_pool` set to `5` can retain up to 20 idle connections per gateway instance. Active connections are outside this limit, so this setting does not cap concurrent requests to the authorization service.

* 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`

  valid value:

  between 200 and 599 inclusive

  ***

  HTTP status code to return to the client when there is a network error with the external authorization service.
