# Forward Auth 配置选项

Forward Auth 插件可与外部授权服务集成，增强 API 安全性和访问控制。<!-- --> <!-- -->配置涵盖静态设置和插件参数。

## 静态配置[​](#static-configurations "静态配置的直接链接")

两个网关级别的配置项会影响 Forward Auth。`http_client` 选择调用授权服务时使用的客户端。`apisix.max_request_headers_readable` 控制可用于转发 `request_headers` 的客户端请求头数量。

这两个配置项从 APISIX 3.20.0 和 API7 企业版 3.10.10 开始可用。较早版本不提供 `http_client`，请求头数量上限固定为 100。

以下示例同时展示这两个配置项。请在对应部署方式的文件中仅加入所需的覆盖项：

* 主机或 Docker
* API7 网关 Helm

在持久化网关配置中加入所需的覆盖项：

config.yaml

```
apisix:

  max_request_headers_readable: 200  # 默认值：100；0 表示读取所有请求头。



plugin_attr:

  forward-auth:

    http_client: lua-resty-http  # 默认原生客户端：ngx_http_ffi_client
```

更新 `config.yaml` 后，重新加载或重启每个网关实例。

`maxRequestHeadersReadable` 配置项需要 API7 网关 Helm Chart 3.10.19 或更高版本。在该网关 Helm release 使用的完整配置文件中加入所需的覆盖项：

values.yaml

```
apisix:

  maxRequestHeadersReadable: 200  # 默认值：100；0 表示读取所有请求头。



pluginAttrs:

  forward-auth:

    http_client: lua-resty-http  # 默认原生客户端：ngx_http_ffi_client
```

按照该网关 Helm release 的常规升级流程应用完整的 Helm 配置文件。

只有当授权服务依赖以下客户端特定行为之一时，才使用 Lua 客户端：

| 行为                                         | 原生客户端                    | Lua 客户端                          |
| -------------------------------------------- | ----------------------------- | ----------------------------------- |
| `Connection` 请求头（不受 `keepalive` 控制） | 发送 `Connection: keep-alive` | 不添加该请求头                      |
| 空的 `GET` 请求                              | 发送 `Content-Length: 0`      | 不添加该请求头                      |
| 默认 `User-Agent`                            | 不添加该请求头                | 发送 `lua-resty-http` 的 User-Agent |
| 响应读取超时                                 | 对完整响应应用一次超时        | 对每次接收操作应用超时              |

请求头配置项只改变插件可见的请求头表，不改变 NGINX 的解析限制；超出插件可见上限的请求头仍可能到达上游。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

* uri

  string

  必填

  ***

  外部授权服务的 URI。

* ssl\_verify

  boolean

  默认值：`true`

  ***

  如果为 true，验证授权服务的 SSL 证书。

* request\_method

  string

  默认值：`GET`

  有效值：

  `GET` 或 `POST`

  ***

  APISIX 用来向外部授权服务发送请求的 HTTP 方法。默认情况下，APISIX 向外部授权服务发送 GET 请求。

  当设置为 `POST` 时，APISIX 会向外部授权服务发送 POST 请求以及请求 Body。但这并不推荐。如果授权决策取决于 POST Body 中的请求参数，建议使用 `$post_arg.*` 提取所需字段，并通过 `extra_headers` 字段传递它们。这种方法避免了发送完整的请求 Body，减少了开销，并使授权服务专注于通过头信息进行决策。

* max\_req\_body\_size

  integer

  默认值：`67108864`

  ***

  当 `request_method` 为 `POST` 时，缓冲并转发到外部授权服务的最大请求体大小，单位为字节（默认 67108864 字节，即 64 MB）。请求体大于此限制的请求将以 HTTP 413 被拒绝。自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。

* request\_headers

  array\[string]

  默认值：`[]`

  ***

  应转发到外部授权服务的客户端请求头。如果未配置，则仅转发 APISIX 添加的头，例如 `X-Forwarded-*`。

* upstream\_headers

  array\[string]

  默认值：`[]`

  ***

  插件在将请求转发到上游前控制的外部授权响应头。授权服务返回已配置的响应头时，网关会转发该响应头；授权响应未返回时，网关会清除客户端提供的同名值。如果未配置，则不转发任何授权响应头。

* client\_headers

  array\[string]

  默认值：`[]`

  ***

  当认证失败时，应转发给客户端的外部授权服务响应头。如果未配置，则没有头会被转发给客户端。

* extra\_headers

  object

  ***

  发送到授权服务的额外头。支持值中的 [内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

* timeout

  integer

  默认值：`3000`

  有效值：

  介于 1 和 60000 之间（含边界值）

  ***

  外部授权服务 HTTP 调用的超时时间（以毫秒为单位）。

* keepalive

  boolean

  默认值：`true`

  ***

  如果为 true，则保持连接打开以用于多个请求。

* keepalive\_timeout

  integer

  默认值：`60000`

  有效值：

  大于或等于 1000

  ***

  建立的 HTTP 连接在关闭前的空闲时间。

* keepalive\_pool

  integer

  默认值：`5`

  有效值：

  大于或等于 1

  ***

  每个 NGINX Worker 进程在一个 keepalive 连接池中保留的最大空闲连接数。Worker 和网关实例之间不共享这些连接池。

  对于一个连接池，若有四个 Worker，且 `keepalive_pool` 设置为 `5`，则每个网关实例最多可保留 20 个空闲连接。活动连接不计入此限制，因此该设置不会限制向认证服务发起的并发请求数。

* allow\_degradation

  boolean

  默认值：`false`

  ***

  如果为 true，允许 APISIX 在插件或其依赖项不可用时继续处理请求（不使用插件）。

* status\_on\_error

  integer

  默认值：`403`

  有效值：

  介于 200 和 599 之间（含边界值）

  ***

  当外部授权服务出现网络错误时，返回给客户端的 HTTP 状态码。
