跳到主要内容

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。

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

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

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 后,重新加载或重启每个网关实例。

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

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

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

参数​

请参阅 插件通用配置 了解所有插件可用的配置选项。

  • 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


    发送到授权服务的额外头。支持值中的 内置变量。

  • 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 状态码。