Forward Auth Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

• uri — string · required

  URI of the external authorization service.

• ssl_verify — boolean · optional · default: true

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

• request_method — string · optional · default: GET

  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

  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: []

  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: []

  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: []

  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

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

• timeout — integer · optional · default: 3000

  Valid values: between 1 and 60000 inclusive

  Timeout for the external authorization service HTTP call in milliseconds.

• keepalive — boolean · optional · default: true

  If true, keep the connections open for multiple requests.

• keepalive_timeout — integer · optional · default: 60000

  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

  Valid values: greater than or equal to 1

  Maximum number of connections in the connection pool.

• allow_degradation — boolean · optional · 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 · optional · default: 403

  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.