Apache APISIX forward-auth 插件详解将认证逻辑下沉到外部服务【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixforward-auth是 Apache APISIX 提供的经典外部认证插件它把身份认证与授权逻辑从网关中剥离出来交由一个专门的外部认证服务处理。通过本文你将掌握该插件的全部配置属性、请求头转发规则、三种典型响应处理方式放行 / 透传响应头 / 失败拦截并能基于 插件源码 与 测试用例 深入理解其底层实现快速在自己的 Route 上落地部署。插件机制概述forward-auth实现的是经典的外部认证Forward Authentication模型APISIX 在收到用户请求后先将请求转发给一个独立的认证服务同时阻塞原始请求只有当认证服务返回 2xx 状态码时才放行原始请求否则由网关将认证服务的响应状态码与自定义响应头直接替换给客户端实现自定义错误信息或重定向到登录页等场景。这种架构将认证与授权逻辑与 API 网关彻底解耦认证策略的变更只需修改外部服务无需动网关配置。从源码看该插件的名称为forward-auth、版本为 0.1优先级为 2002apisix/plugins/forward-auth.lua#L72-L77在插件执行链中处于较高的执行顺序。属性Attributes详解插件的完整配置项如下表所示默认值、取值范围均与 schema 定义 保持一致名称类型必选项默认值有效值描述uristring是认证服务authorization service的地址例如https://localhost:9188。这是唯一必填项schema 校验为required {uri}ssl_verifyboolean否true当设置为true时验证 SSL 证书请求 HTTPS 认证服务时建议保持默认开启request_methodstring否GET[GET,POST]客户端向认证服务发送请求的方法。当设置为POST时会将客户端request body一并转发给认证服务request_headersarray[string]否需要由客户端转发到认证服务的请求头白名单。如果没有设置则只发送 APISIX 自动生成的 headers如X-Forwarded-XXX系列upstream_headersarray[string]否认证通过时认证服务响应中需要转发给 Upstream 的响应头。如果不设置则不转发任何响应头client_headersarray[string]否认证失败时由认证服务向客户端发送的响应头用于自定义错误提示、重定向 Location 等。如果不设置则不转发任何响应头timeoutinteger否3000ms[1, 60000]ms认证服务 HTTP 调用超时时间毫秒keepaliveboolean否true是否启用 HTTP 长连接为多个请求复用连接keepalive_timeoutinteger否60000ms[1000, ...]ms长连接空闲超时时间毫秒超过后连接被关闭keepalive_poolinteger否5[1, ...]长连接池大小上限allow_degradationboolean否false当设置为true时允许在认证服务器不可用时跳过认证直接放行降级容错status_on_errorinteger否403[200,...,599]认证服务出现网络错误时返回给客户端的 HTTP 状态码默认 403其中request_method的枚举约束、timeout的 [1, 60000] 毫秒区间、status_on_error的 [200, 599] 区间都直接来源于 schema 定义。在 sanity 测试 中可以看到缺失uri会报property uri is requireduri传数字会报类型错误request_method传PUT会报matches none of the enum valuesrequest_headers传字符串而非数组也会被拒绝——说明这些参数在配置阶段即被严格校验。安全相关的配置校验在check_schema阶段插件除了做基础 schema 校验外还调用了两条安全检查逻辑apisix/plugins/forward-auth.lua#L80-L86core.utils.check_https({uri}, conf, _M.name)检测uri中是否混用http://与https://等不安全写法apisix/core/utils.lua#L423-L444core.utils.check_tls_bool({ssl_verify}, conf, _M.name)当ssl_verify被显式设为false时输出安全风险告警日志apisix/core/utils.lua#L447-L462提示关闭 TLS 校验属于安全风险。数据定义网关自动生成的转发请求头APISIX 在调用认证服务时会自动生成并发送以下五类请求头apisix/plugins/forward-auth.lua#L90-L96帮助认证服务还原原始请求的上下文SchemeHTTP MethodHostURISource IPX-Forwarded-ProtoX-Forwarded-MethodX-Forwarded-HostX-Forwarded-UriX-Forwarded-For它们的取值分别来自core.request.get_scheme(ctx)、core.request.get_method()、core.request.get_host(ctx)、ctx.var.request_uri与core.request.get_remote_client_ip(ctx)。值得注意的是这些生成的头字段优先于request_headers白名单中的同名配置——在 TEST 6 中客户端即使伪造了X-Forwarded-Host: apisix.apache.org认证服务收到的仍然是网关计算的X-Forwarded-Host: localhost从测试断言response_body_unlike可以看出客户端伪造值被忽略保证了认证请求上下文不可被客户端篡改。当request_method设置为POST时插件还会额外透传Content-Length、Expect、Transfer-Encoding、Content-Encoding等与请求体相关的头字段apisix/plugins/forward-auth.lua#L98-L103。这在 forward-auth2.t 的测试中有专门验证POST模式下认证服务能收到Content-Length/Transfer-Encoding/Content-Encoding而GET模式下则不会收到。使用示例完整上手流程下面以官方文档示例为主线完整演示从搭建认证服务到验证三种认证结果的整个流程。前提准备获取 admin_keyAdmin API 请求需要携带X-API-KEY头可以从config.yaml中提取并存入环境变量admin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)第一步搭建外部认证服务这里使用 APISIX 自身的 serverless-pre-function 插件模拟一个认证服务它读取请求的Authorization头值为123时认证通过返回 200值为321时认证通过并附带X-User-ID响应头否则返回 403 并携带Location重定向头curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/auth \ -H X-API-KEY: $admin_key \ -H Content-Type: application/json \ -d { uri: /auth, plugins: { serverless-pre-function: { phase: rewrite, functions: [ return function (conf, ctx) local core require(\apisix.core\); local authorization core.request.header(ctx, \Authorization\); if authorization \123\ then core.response.exit(200); elseif authorization \321\ then core.response.set_header(\X-User-ID\, \i-am-user\); core.response.exit(200); else core.response.set_header(\Location\, \http://example.com/auth\); core.response.exit(403); end end ] } } }第二步在 Route 上启用 forward-auth 插件将forward-auth插件挂载到目标 Route/headers上并把上游指向httpbin.org。这里的配置同时用到了三类头白名单curl -X PUT http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: $admin_key \ -d { uri: /headers, plugins: { forward-auth: { uri: http://127.0.0.1:9080/auth, request_headers: [Authorization], upstream_headers: [X-User-ID], client_headers: [Location] } }, upstream: { nodes: { httpbin.org:80: 1 }, type: roundrobin } }配置含义客户端请求中的Authorization头会透传给认证服务认证通过时认证服务响应里的X-User-ID头会被注入到发往 Upstream 的请求中认证失败时认证服务响应里的Location头会被回传给客户端。第三步验证三种认证结果场景一认证通过正常转发到 Upstreamcurl http://127.0.0.1:9080/headers -H Authorization: 123{ headers: { Authorization: 123, Next: More-headers } }认证服务返回 200原始请求被放行Upstreamhttpbin正常返回其收到的请求头。场景二认证通过且把认证服务的响应头透传给 Upstreamcurl http://127.0.0.1:9080/headers -H Authorization: 321{ headers: { Authorization: 321, X-User-ID: i-am-user, Next: More-headers } }由于配置了upstream_headers: [X-User-ID]认证服务返回的X-User-ID: i-am-user被 core.request.set_header 写入转发请求最终出现在 Upstream 收到的请求头中——这是典型的认证服务向业务服务传递用户身份模式。场景三认证失败自定义响应回给客户端curl -i http://127.0.0.1:9080/headersHTTP/1.1 403 Forbidden Location: http://example.com/auth认证服务返回非 2xx这里是 403插件立刻终止原始请求将认证服务的状态码与client_headers白名单中的Location头替换给客户端。Location头可用于实现重定向到登录页的经典场景。底层实现access 阶段的关键逻辑forward-auth的全部认证逻辑集中在access阶段apisix/plugins/forward-auth.lua#L89-L167其核心流程可概括为组装请求头生成X-Forwarded-*系列头追加request_headers白名单中的客户端请求头POST模式下再补充请求体相关头发起认证调用通过resty.http的request_uri向conf.uri发起请求ssl_verify、keepalive、timeout等参数一并生效POST模式下优先使用get_client_body_reader()流式转发请求体失败时回退到core.request.get_body()apisix/plugins/forward-auth.lua#L121-L132这保证了 11MB 级别的大请求体也能被正确转发——对应 TEST 14test large body异常降级处理如果认证调用本身失败网络错误、连接被拒等且allow_degradation为true则直接放行跳过认证否则记录告警日志并以status_on_error指定的状态码默认 403结束请求apisix/plugins/forward-auth.lua#L139-L145。TEST 11 与 TEST 12 分别验证了认证服务不可用时的返回 403与降级放行 200两种行为按状态码分流res.status 300时视为认证失败把client_headers白名单中的响应头设置到客户端响应并返回认证服务的状态码与 body2xx 时则把upstream_headers白名单中的响应头注入后续的 Upstream 请求apisix/plugins/forward-auth.lua#L147-L166。注意client_headers与upstream_headers的生效是有条件的——测试 TEST 7 和 TEST 8 表明当 Route 未配置对应白名单时认证服务返回的头不会被透传白名单即转发开关。另外keepalive相关的keepalive_timeout、keepalive_pool只有在conf.keepalive为true时才会被写入请求参数apisix/plugins/forward-auth.lua#L134-L137与属性表中的默认值语义一致。删除插件需要禁用forward-auth插件时只需将 Route 配置中的plugins置空或移除该插件的 JSON 配置块重新 PUT 即可。APISIX 会自动热加载配置变更无需重启服务curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { methods: [GET], uri: /hello, plugins: {}, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } } }小结forward-auth插件的核心价值在于把认证/授权从网关中抽离为独立服务通过X-Forwarded-*系列头还原请求上下文借助request_headers/upstream_headers/client_headers三组白名单精确控制客户端 → 认证服务 → Upstream → 客户端各环节的信息流动同时用timeout、keepalive、allow_degradation、status_on_error覆盖了超时、连接复用与故障降级等生产环境关键诉求。若需深入源码可重点阅读 插件实现schema 校验与 access 逻辑、工具校验函数HTTPS 与 TLS 安全检查以及 forward-auth.t 与 forward-auth2.t 两个测试文件覆盖 header 转发、POST 大请求体、降级与错误码等 19 个测试场景。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考