Forward Auth 配置选项
Forward Auth 插件可与外部授权服务集成,增强 API 安全性和访问控制。 配置涵盖静态设置和插件参数。
静态配置
两个网关级别的配置项会影响 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
在持久化网关配置中加入所需的覆盖项:
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 使用的完整配置文件中加入所需的覆盖项:
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 的解析限制;超出插件可见上限的请求头仍可能到达上游。
参数
请参阅 插件通用配置 了解所有插件可用的配置选项。
uri
外部授权服务的 URI。
ssl_verify
如果为 true,验证授 权服务的 SSL 证书。
request_method
有效值:
GET或POSTAPISIX 用来向外部授权服务发送请求的 HTTP 方法。默认情况下,APISIX 向外部授权服务发送 GET 请求。
当设置为
POST时,APISIX 会向外部授权服务发送 POST 请求以及请求 Body。但这并不推荐。如果授权决策取决于 POST Body 中的请求参数,建议使用$post_arg.*提取所需字段,并通过extra_headers字段传递它们。这种方法避免了发送完整的请求 Body,减少了开销,并使授权服务专注于通过头信息进行决策。max_req_body_size
当
request_method为POST时,缓冲并转发到外部授权服务的最大请求体大小,单位为字节(默认 67108864 字节,即 64 MB)。请求体大于此限制的请求将以 HTTP 413 被拒绝。自 API7 企业版 3.9.14 和 APISIX 3.17.0 起可用。request_headers
应转发到外部授权服务的客户端请求头。如果未配置,则仅转发 APISIX 添加的头,例如
X-Forwarded-*。upstream_headers
插件在将请求转发到上游前控制的外部授权响应头。授权服务返回已配置的响应头时,网关会转发该响应头;授权响应未返回时,网关会清除客户端提供的同名值。如果未配置,则不转发任何授权响应头。
client_headers
当认证失败时,应转发给客户端的外部授权服务响应头。如果未配置,则没有头会被转发给客户端。
extra_headers
发送到授权服务的额外头。支持值中的 内置变量。
timeout
有效值:
介于 1 和 60000 之间(含边界值)外部授权服务 HTTP 调用的超时时间(以毫秒为单位)。
keepalive
如果为 true,则保持连接打开以用于多个请求。
keepalive_timeout
有效值:
大于或等于 1000建立的 HTTP 连接在关闭前的空闲时间。
keepalive_pool
有效值:
大于或等于 1每个 NGINX Worker 进程在一个 keepalive 连接池中保留的最大空闲连接数。Worker 和网关实例之间不共享这些连接池。
对于一个连接池,若有四个 Worker,且
keepalive_pool设置为5,则每个网关实例最多可保留 20 个空闲连接。活动连接不计入此限制,因此该设置不会限制向认证服务发起的并发请求数。allow_degradation
如果为 true,允许 APISIX 在插件或其依赖项不可用时继续处理请求(不使用插件)。
status_on_error
有效值:
介于 200 和 599 之间(含边界值)当外部授权服务出现网络错误时,返回给客户端的 HTTP 状态码。