Ingress NGINX Controller 外部认证External Auth实战指南基于 auth-url 注解实现外置 Basic 认证【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读本文围绕 Kubernetes Ingress NGINX Controller 的外部认证External Authentication能力展开以仓库中 docs/examples/auth/external-auth/README.md 提供的完整示例为主线讲解如何通过nginx.ingress.kubernetes.io/auth-url注解将请求转发给一个独立的外部认证服务进行鉴权。读完本文你将掌握外部认证 Ingress 的完整 YAML 写法、不带凭据 / 带正确凭据 / 带错误凭据三种请求的预期响应差异401 vs 200、auth-url注解族的全部配套参数缓存、keepalive、响应头透传、错误页跳转等以及底层实现原理auth_request子请求机制、Lua 变量共享与_external-auth内部 location 的生成逻辑。场景概述为什么需要外部认证Kubernetes Ingress 最常见的认证方式是“Basic Auth / Digest Auth”——控制器直接在 Nginx 层用htpasswd校验用户名密码。但很多真实场景需要将鉴权逻辑交给已有的、独立的认证服务去完成例如认证服务已经对接了公司统一的 LDAP / OAuth / SSO 平台需要把用户名、密码以外的上下文如来源 IP、请求头、原始 URL一并交给认证方判断需要对不同路由使用不同的认证策略或在认证失败时跳转到统一的登录页。Ingress NGINX Controller 通过External Authentication外部认证注解族解决这类需求Ingress 收到请求后先把该请求以子请求的形式发送到auth-url指定的认证服务只有认证服务返回 2xx 时才放行到真正的后端返回 401/403 则直接拒绝。仓库中的 docs/user-guide/nginx-configuration/annotations.md 对此做了精确定义只需给 Ingress 加上nginx.ingress.kubernetes.io/auth-url注解即可指示控制器“认证请求应当发往哪个 URL”。示例 1使用外部服务做 Basic Auth示例中的认证服务直接复用公网服务https://httpbin.org/basic-auth/user/passwd即用户名为user、密码为passwd。这是把外部认证流程讲清楚最直观的方式——无需自建认证后端即可验证整套链路。部署 Ingress示例的完整清单位于 ingress.yamlapiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd name: external-auth spec: ingressClassName: nginx rules: - host: external-auth-01.sample.com http: paths: - path: / pathType: Prefix backend: service: name: http-svc port: number: 80关键点解读nginx.ingress.kubernetes.io/auth-url唯一必填的外部认证注解值必须是一个合法的 URL支持携带 Nginx 变量如$host、$request_uri。在源码 internal/ingress/annotations/authreq/main.go 中该注解的校验器为parser.ValidateRegex(parser.URLWithNginxVariableRegex, true)且风险等级被标记为AnnotationRiskHigh——因为它把请求的鉴权责任完全委托给了外部服务配置错误会直接导致路由不可用。ingressClassName: nginx显式绑定到 NGINX IngressClass确保由本控制器接管。pathType: Prefixpath: /对external-auth-01.sample.com域名下的所有路径启用认证。使用kubectl创建并确认$ kubectl create -f ingress.yaml ingress external-auth created $ kubectl get ing external-auth NAME HOSTS ADDRESS PORTS AGE external-auth external-auth-01.sample.com 172.17.4.99 80 13s创建成功后控制器会为该 Ingress 生成一个包含auth_request指令的 Nginx 配置真正的流量先经/ _external-auth-...这个内部 location 完成鉴权鉴权通过后才转发到http-svc后端。认证链路的工作原理源码视角从控制器源码 internal/ingress/controller/template/template.go 可以看到buildAuthLocation函数会为每个启用了外部认证的 location 生成一个内部鉴权路径return fmt.Sprintf(/_external-auth-%v-%v, str, pathType)其中str是原始路径的 Base64Raw URLEncoding编码pathType是路径匹配类型如Prefix。也就是说每个 location 都会生成独立的内部认证入口。在同一个文件里buildAuthResponseHeaderstemplate.go揭示了认证响应的处理方式Nginx 的auth_request模块会把认证子请求的响应头放进$upstream_http_header变量中控制器据此生成auth_request_set $authHeaderN $upstream_http_xxx;指令把认证服务返回的自定义头透传给上游后端。源码注释还特别指出auth_request模块存在忽略 keepalive 指令的已知限制nginx ticket #1579因此控制器会改用 Lua 与 Nginx 变量模拟同样的功能。测试 1不带用户名/密码预期返回 401认证的核心特征就是“没凭据必须被拦下”。对未携带凭据的请求httpbin 的/basic-auth/user/passwd会返回 401Ingress NGINX Controller 随之将 401 直接返回给客户端绝不会转发到后端$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) GET / HTTP/1.1 Host: external-auth-01.sample.com User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 401 Unauthorized Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:52:08 GMT Content-Type: text/html Content-Length: 195 Connection: keep-alive WWW-Authenticate: Basic realmFake Realm html headtitle401 Authorization Required/title/head body bgcolorwhite centerh1401 Authorization Required/h1/center hrcenternginx/1.11.3/center /body /html * Connection #0 to host 172.17.4.99 left intact注意两个细节响应中的WWW-Authenticate: Basic realmFake Realm直接来自 httpbin 认证服务本身而不是 Nginx Ingress——说明401 响应体与挑战头完全由外部认证服务生成并原样透传给客户端。由于示例使用公网服务演示实际生产环境中建议用-k或为认证服务配置合法证书认证服务是否通过 HTTPS 由auth-url的 scheme 决定。测试 2携带有效用户名/密码预期返回 200使用-u user:passwd携带 Basic Auth 凭据时curl 会生成Authorization: Basic dXNlcjpwYXNzd2Q头httpbin 校验通过后返回 200认证子请求成功Ingress 放行请求到http-svc后端$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com -u user:passwd * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) * Server auth using Basic with user user GET / HTTP/1.1 Host: external-auth-01.sample.com Authorization: Basic dXNlcjpwYXNzd2Q User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 200 OK Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:52:50 GMT Content-Type: text/plain Transfer-Encoding: chunked Connection: keep-alive CLIENT VALUES: client_address10.2.60.2 commandGET real path/ querynil request_version1.1 request_urihttp://external-auth-01.sample.com:8080/ SERVER VALUES: server_versionnginx: 1.9.11 - lua: 10001 HEADERS RECEIVED: accept*/* authorizationBasic dXNlcjpwYXNzd2Q connectionclose hostexternal-auth-01.sample.com user-agentcurl/7.50.1 x-forwarded-for10.2.60.1 x-forwarded-hostexternal-auth-01.sample.com x-forwarded-port80 x-forwarded-protohttp x-real-ip10.2.60.1 BODY: * Connection #0 to host 172.17.4.99 left intact -no body in request-这段响应实际上来自 http-svc 回显服务它把收到的请求头原样打印出来因此可以清楚看到认证通过后进入后端的请求形态authorizationBasic dXNlcjpwYXNzd2Q原始 Authorization 头默认会被转发到后端。若你的后端不需要明文密码或不想把凭据暴露给后端可以在认证完成后通过auth-response-headers选择性地透传认证服务返回的受控头并配合auth-snippet自定义转发策略。x-forwarded-for10.2.60.1、x-real-ip10.2.60.1Ingress 保留了客户端真实 IP 并透传便于后端做审计。server_versionnginx: 1.9.11 - lua: 10001证明流量确实经过 Nginx Lua 层Ingress NGINX Controller 的请求处理大量依赖 OpenResty Lua 模块。测试 3携带错误用户名/密码预期返回 401把密码改成user错误密码后httpbin 校验失败返回 401请求同样被拦下$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com -u user:user * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) * Server auth using Basic with user user GET / HTTP/1.1 Host: external-auth-01.sample.com Authorization: Basic dXNlcjp1c2Vy User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 401 Unauthorized Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:53:04 GMT Content-Type: text/html Content-Length: 195 Connection: keep-alive * Authentication problem. Ignoring this. WWW-Authenticate: Basic realmFake Realm html headtitle401 Authorization Required/title/head body bgcolorwhite centerh1401 Authorization Required/h1/center hrcenternginx/1.11.3/center /body /html * Connection #0 to host 172.17.4.99 left intact三个测试放在一起形成了完整的行为闭环测试场景携带凭据认证服务结果最终 HTTP 状态码测试 1无用户名/密码无401401测试 2有效用户名/密码user:passwd200200放行到后端测试 3错误用户名/密码user:user401401auth-url 注解族完整参数指南示例只使用了最小配置auth-url但在生产环境中annotations.md 与源码 authreq/main.go 共同定义了完整的注解族可按需组合注解说明默认值 / 约束nginx.ingress.kubernetes.io/auth-url认证服务 URL必填支持 Nginx 变量必须是合法 URLnginx.ingress.kubernetes.io/auth-method认证请求使用的 HTTP 方法仅允许 GET/HEAD/POST/PUT/PATCH/DELETE/CONNECT/OPTIONS/TRACE见 main.go 中methodsRegexnginx.ingress.kubernetes.io/auth-signin认证失败时的跳转登录页地址可选nginx.ingress.kubernetes.io/auth-signin-redirect-param登录页 URL 参数名用于携带原始请求 URL可选nginx.ingress.kubernetes.io/auth-response-headers认证通过后透传给后端的响应头列表逗号分隔头名须匹配^[a-zA-Z\d\-_]$nginx.ingress.kubernetes.io/auth-proxy-set-headers一个 ConfigMap 名称其中的键值对作为额外请求头发给认证服务仅限同命名空间除非启用跨命名空间资源nginx.ingress.kubernetes.io/auth-request-redirect设置X-Auth-Request-Redirect头的值可选nginx.ingress.kubernetes.io/auth-cache-key开启认证结果缓存并指定缓存键如$remote_user$http_authorization每个 server/location 拥有独立 keyspacenginx.ingress.kubernetes.io/auth-cache-duration按状态码指定缓存时长如200 202 30m支持逗号分隔多组默认200 202 401 5mnginx.ingress.kubernetes.io/auth-keepalive到 auth-url 的最大 keepalive 连接数默认0禁用URL host 部分含$变量时强制为 0nginx.ingress.kubernetes.io/auth-keepalive-share-vars是否在当前请求与认证请求之间共享 Nginx 变量如让 X-Request-ID 保持一致默认falsenginx.ingress.kubernetes.io/auth-keepalive-requests单条 keepalive 连接可服务最大请求数默认1000仅当auth-keepalive 0时生效nginx.ingress.kubernetes.io/auth-keepalive-timeout空闲 keepalive 连接保持时长秒默认60nginx.ingress.kubernetes.io/auth-always-set-cookie是否始终设置认证请求返回的 cookie默认仅当状态码为 200/201/204/206/301/302/303/304/307/308 时设置nginx.ingress.kubernetes.io/auth-snippet追加到认证 location 的自定义 Nginx 配置片段必须与auth-url配合使用风险等级 Critical注意auth-keepalive在 HTTP/2 监听器下因 Lua subrequest 的限制而无法工作使用前应确认 ConfigMap 中的use-http2已关闭详见 annotations.md 中的提示。认证缓存与 keepalive 的源码级细节缓存auth-cache-duration的解析与校验在 authreq/main.go 的ValidCacheDuration中实现语法为“状态码 时长”序列时长支持ms/s/m/h/d/w/M/y单位对应 Nginx 官方语法ParseStringToCacheDurations保证至少返回默认值200 202 401 5m。这相当于为认证结果启用了proxy_cache_valid语义可显著降低认证服务的压力。keepalive 降级逻辑源码 authreq/main.go 显示一旦auth-keepalive、auth-keepalive-requests或auth-keepalive-timeout出现负值或auth-url的 host 部分包含$变量控制器都会把连接数强制回退到 0禁用 keepalive以避免生成无效的 Nginx upstream。keepalive 的 Lua 替代实现模板源码 template.go 的注释明确指出由于auth_request模块忽略 keepalive 指令nginx ticket #1579启用 keepalive 时控制器改用access_by_lua_block模拟同等功能。典型组合示例认证 登录页跳转 结果缓存apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-with-external-auth annotations: nginx.ingress.kubernetes.io/auth-url: https://auth.example.com/verify nginx.ingress.kubernetes.io/auth-method: POST nginx.ingress.kubernetes.io/auth-signin: https://auth.example.com/login?rd$scheme://$host$request_uri nginx.ingress.kubernetes.io/auth-signin-redirect-param: rd nginx.ingress.kubernetes.io/auth-response-headers: X-Auth-User, X-Auth-Groups nginx.ingress.kubernetes.io/auth-cache-key: $remote_user$http_authorization nginx.ingress.kubernetes.io/auth-cache-duration: 200 202 10m, 401 5m nginx.ingress.kubernetes.io/auth-keepalive: 50 nginx.ingress.kubernetes.io/auth-keepalive-requests: 500 nginx.ingress.kubernetes.io/auth-keepalive-timeout: 60 spec: ingressClassName: nginx rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: app-svc port: number: 80全局外部认证与灰度控制除了按 Ingress 逐条配置控制器还支持在 ConfigMap 中设置global-auth-url实现全局外部认证一旦设置所有 Ingress 请求默认都会先经过认证。若某条路由需要豁免则在其 Ingress 上显式添加nginx.ingress.kubernetes.io/enable-global-auth: false默认值为true。该机制的解析入口位于 internal/ingress/controller/template/configmap.go对应逻辑在shouldApplyGlobalAuthtemplate.go中体现仅当该 location未设置auth-url、全局地址非空且enable-global-auth为真时才套用全局认证。单元测试与端到端验证仓库为外部认证提供了充足的自动化保障可作为理解行为边界的参考注解解析单元测试internal/ingress/annotations/authreq/main_test.go 覆盖了 URL 合法性缺 scheme、非法 host、多级域名、auth-method、auth-response-headers、auth-cache-duration含“只有状态码无时长”“时长在状态码之前”等非法输入、keepalive 系列参数默认值及负值降级、以及auth-proxy-set-headers从 ConfigMap 读取头的场景。端到端测试test/e2e/annotations/auth.go 验证了“未配置认证时返回 200”“认证配置了无效 secret 时返回 503”“配置了认证但缺少 Authorization 头时返回 401”等真实行为。生产落地建议认证服务可用性是第一优先级外部认证是请求链路上的硬依赖认证服务不可用会直接导致 401/5xx 拦截流量。请为认证服务配置健康检查、限流与高可用并利用auth-cache-duration缓存认证结果以削减峰值请求。HTTPS 与证书生产环境auth-url应指向内部 HTTPS 服务认证服务返回 401 时携带的WWW-Authenticate挑战头会被原样透传可用于指导客户端弹窗行为。凭据泄露面控制原始Authorization头默认会透传到后端若后端无需明文凭据应使用auth-response-headers只透传认证服务返回的受控头。安全等级感知源码将auth-url标为高风险AnnotationRiskHigh、auth-snippet标为 Critical。若控制器开启了annotations-risk-level校验见 annotations-risk.md高/危风险注解的启用需要相应的安全配置放行切勿将敏感认证配置随意授予不可信用户。优先使用内部认证服务本文示例使用公网 httpbin 仅用于演示链路真实环境应部署在集群内避免把流量和凭据发给第三方。小结通过nginx.ingress.kubernetes.io/auth-urlIngress NGINX Controller 把“认证”与“路由”解耦鉴权逻辑完全由外部服务裁决控制器只负责在auth_request子请求失败时拦截、成功时放行并将认证结果响应头、cookie按需透传。本文的“无凭据 401 → 正确凭据 200 → 错误凭据 401”三段式验证配合auth-cache-*、auth-keepalive-*、auth-signin等扩展参数已经覆盖了从最小可用配置到生产级外部认证方案的完整链路。若需要进一步了解全局认证配置可查阅 configmap.md 中 global-auth-url 一节。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ingress NGINX Controller 外部认证External Auth实战指南基于 auth-url 注解实现外置 Basic 认证【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx导读本文围绕 Kubernetes Ingress NGINX Controller 的外部认证External Authentication能力展开以仓库中 docs/examples/auth/external-auth/README.md 提供的完整示例为主线讲解如何通过nginx.ingress.kubernetes.io/auth-url注解将请求转发给一个独立的外部认证服务进行鉴权。读完本文你将掌握外部认证 Ingress 的完整 YAML 写法、不带凭据 / 带正确凭据 / 带错误凭据三种请求的预期响应差异401 vs 200、auth-url注解族的全部配套参数缓存、keepalive、响应头透传、错误页跳转等以及底层实现原理auth_request子请求机制、Lua 变量共享与_external-auth内部 location 的生成逻辑。场景概述为什么需要外部认证Kubernetes Ingress 最常见的认证方式是“Basic Auth / Digest Auth”——控制器直接在 Nginx 层用htpasswd校验用户名密码。但很多真实场景需要将鉴权逻辑交给已有的、独立的认证服务去完成例如认证服务已经对接了公司统一的 LDAP / OAuth / SSO 平台需要把用户名、密码以外的上下文如来源 IP、请求头、原始 URL一并交给认证方判断需要对不同路由使用不同的认证策略或在认证失败时跳转到统一的登录页。Ingress NGINX Controller 通过External Authentication外部认证注解族解决这类需求Ingress 收到请求后先把该请求以子请求的形式发送到auth-url指定的认证服务只有认证服务返回 2xx 时才放行到真正的后端返回 401/403 则直接拒绝。仓库中的 docs/user-guide/nginx-configuration/annotations.md 对此做了精确定义只需给 Ingress 加上nginx.ingress.kubernetes.io/auth-url注解即可指示控制器“认证请求应当发往哪个 URL”。示例 1使用外部服务做 Basic Auth示例中的认证服务直接复用公网服务https://httpbin.org/basic-auth/user/passwd即用户名为user、密码为passwd。这是把外部认证流程讲清楚最直观的方式——无需自建认证后端即可验证整套链路。部署 Ingress示例的完整清单位于 ingress.yamlapiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: nginx.ingress.kubernetes.io/auth-url: https://httpbin.org/basic-auth/user/passwd name: external-auth spec: ingressClassName: nginx rules: - host: external-auth-01.sample.com http: paths: - path: / pathType: Prefix backend: service: name: http-svc port: number: 80关键点解读nginx.ingress.kubernetes.io/auth-url唯一必填的外部认证注解值必须是一个合法的 URL支持携带 Nginx 变量如$host、$request_uri。在源码 internal/ingress/annotations/authreq/main.go 中该注解的校验器为parser.ValidateRegex(parser.URLWithNginxVariableRegex, true)且风险等级被标记为AnnotationRiskHigh——因为它把请求的鉴权责任完全委托给了外部服务配置错误会直接导致路由不可用。ingressClassName: nginx显式绑定到 NGINX IngressClass确保由本控制器接管。pathType: Prefixpath: /对external-auth-01.sample.com域名下的所有路径启用认证。使用kubectl创建并确认$ kubectl create -f ingress.yaml ingress external-auth created $ kubectl get ing external-auth NAME HOSTS ADDRESS PORTS AGE external-auth external-auth-01.sample.com 172.17.4.99 80 13s创建成功后控制器会为该 Ingress 生成一个包含auth_request指令的 Nginx 配置真正的流量先经/ _external-auth-...这个内部 location 完成鉴权鉴权通过后才转发到http-svc后端。认证链路的工作原理源码视角从控制器源码 internal/ingress/controller/template/template.go 可以看到buildAuthLocation函数会为每个启用了外部认证的 location 生成一个内部鉴权路径return fmt.Sprintf(/_external-auth-%v-%v, str, pathType)其中str是原始路径的 Base64Raw URLEncoding编码pathType是路径匹配类型如Prefix。也就是说每个 location 都会生成独立的内部认证入口。在同一个文件里buildAuthResponseHeaderstemplate.go揭示了认证响应的处理方式Nginx 的auth_request模块会把认证子请求的响应头放进$upstream_http_header变量中控制器据此生成auth_request_set $authHeaderN $upstream_http_xxx;指令把认证服务返回的自定义头透传给上游后端。源码注释还特别指出auth_request模块存在忽略 keepalive 指令的已知限制nginx ticket #1579因此控制器会改用 Lua 与 Nginx 变量模拟同样的功能。测试 1不带用户名/密码预期返回 401认证的核心特征就是“没凭据必须被拦下”。对未携带凭据的请求httpbin 的/basic-auth/user/passwd会返回 401Ingress NGINX Controller 随之将 401 直接返回给客户端绝不会转发到后端$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) GET / HTTP/1.1 Host: external-auth-01.sample.com User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 401 Unauthorized Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:52:08 GMT Content-Type: text/html Content-Length: 195 Connection: keep-alive WWW-Authenticate: Basic realmFake Realm html headtitle401 Authorization Required/title/head body bgcolorwhite centerh1401 Authorization Required/h1/center hrcenternginx/1.11.3/center /body /html * Connection #0 to host 172.17.4.99 left intact注意两个细节响应中的WWW-Authenticate: Basic realmFake Realm直接来自 httpbin 认证服务本身而不是 Nginx Ingress——说明401 响应体与挑战头完全由外部认证服务生成并原样透传给客户端。由于示例使用公网服务演示实际生产环境中建议用-k或为认证服务配置合法证书认证服务是否通过 HTTPS 由auth-url的 scheme 决定。测试 2携带有效用户名/密码预期返回 200使用-u user:passwd携带 Basic Auth 凭据时curl 会生成Authorization: Basic dXNlcjpwYXNzd2Q头httpbin 校验通过后返回 200认证子请求成功Ingress 放行请求到http-svc后端$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com -u user:passwd * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) * Server auth using Basic with user user GET / HTTP/1.1 Host: external-auth-01.sample.com Authorization: Basic dXNlcjpwYXNzd2Q User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 200 OK Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:52:50 GMT Content-Type: text/plain Transfer-Encoding: chunked Connection: keep-alive CLIENT VALUES: client_address10.2.60.2 commandGET real path/ querynil request_version1.1 request_urihttp://external-auth-01.sample.com:8080/ SERVER VALUES: server_versionnginx: 1.9.11 - lua: 10001 HEADERS RECEIVED: accept*/* authorizationBasic dXNlcjpwYXNzd2Q connectionclose hostexternal-auth-01.sample.com user-agentcurl/7.50.1 x-forwarded-for10.2.60.1 x-forwarded-hostexternal-auth-01.sample.com x-forwarded-port80 x-forwarded-protohttp x-real-ip10.2.60.1 BODY: * Connection #0 to host 172.17.4.99 left intact -no body in request-这段响应实际上来自 http-svc 回显服务它把收到的请求头原样打印出来因此可以清楚看到认证通过后进入后端的请求形态authorizationBasic dXNlcjpwYXNzd2Q原始 Authorization 头默认会被转发到后端。若你的后端不需要明文密码或不想把凭据暴露给后端可以在认证完成后通过auth-response-headers选择性地透传认证服务返回的受控头并配合auth-snippet自定义转发策略。x-forwarded-for10.2.60.1、x-real-ip10.2.60.1Ingress 保留了客户端真实 IP 并透传便于后端做审计。server_versionnginx: 1.9.11 - lua: 10001证明流量确实经过 Nginx Lua 层Ingress NGINX Controller 的请求处理大量依赖 OpenResty Lua 模块。测试 3携带错误用户名/密码预期返回 401把密码改成user错误密码后httpbin 校验失败返回 401请求同样被拦下$ curl -k http://172.17.4.99 -v -H Host: external-auth-01.sample.com -u user:user * Rebuilt URL to: http://172.17.4.99/ * Trying 172.17.4.99... * Connected to 172.17.4.99 (172.17.4.99) port 80 (#0) * Server auth using Basic with user user GET / HTTP/1.1 Host: external-auth-01.sample.com Authorization: Basic dXNlcjp1c2Vy User-Agent: curl/7.50.1 Accept: */* HTTP/1.1 401 Unauthorized Server: nginx/1.11.3 Date: Mon, 03 Oct 2016 14:53:04 GMT Content-Type: text/html Content-Length: 195 Connection: keep-alive * Authentication problem. Ignoring this. WWW-Authenticate: Basic realmFake Realm html headtitle401 Authorization Required/title/head body bgcolorwhite centerh1401 Authorization Required/h1/center hrcenternginx/1.11.3/center /body /html * Connection #0 to host 172.17.4.99 left intact三个测试放在一起形成了完整的行为闭环测试场景携带凭据认证服务结果最终 HTTP 状态码测试 1无用户名/密码无401401测试 2有效用户名/密码user:passwd200200放行到后端测试 3错误用户名/密码user:user401401auth-url 注解族完整参数指南示例只使用了最小配置auth-url但在生产环境中annotations.md 与源码 authreq/main.go 共同定义了完整的注解族可按需组合注解说明默认值 / 约束nginx.ingress.kubernetes.io/auth-url认证服务 URL必填支持 Nginx 变量必须是合法 URLnginx.ingress.kubernetes.io/auth-method认证请求使用的 HTTP 方法仅允许 GET/HEAD/POST/PUT/PATCH/DELETE/CONNECT/OPTIONS/TRACE见 main.go 中methodsRegexnginx.ingress.kubernetes.io/auth-signin认证失败时的跳转登录页地址可选nginx.ingress.kubernetes.io/auth-signin-redirect-param登录页 URL 参数名用于携带原始请求 URL可选nginx.ingress.kubernetes.io/auth-response-headers认证通过后透传给后端的响应头列表逗号分隔头名须匹配^[a-zA-Z\d\-_]$nginx.ingress.kubernetes.io/auth-proxy-set-headers一个 ConfigMap 名称其中的键值对作为额外请求头发给认证服务仅限同命名空间除非启用跨命名空间资源nginx.ingress.kubernetes.io/auth-request-redirect设置X-Auth-Request-Redirect头的值可选nginx.ingress.kubernetes.io/auth-cache-key开启认证结果缓存并指定缓存键如$remote_user$http_authorization每个 server/location 拥有独立 keyspacenginx.ingress.kubernetes.io/auth-cache-duration按状态码指定缓存时长如200 202 30m支持逗号分隔多组默认200 202 401 5mnginx.ingress.kubernetes.io/auth-keepalive到 auth-url 的最大 keepalive 连接数默认0禁用URL host 部分含$变量时强制为 0nginx.ingress.kubernetes.io/auth-keepalive-share-vars是否在当前请求与认证请求之间共享 Nginx 变量如让 X-Request-ID 保持一致默认falsenginx.ingress.kubernetes.io/auth-keepalive-requests单条 keepalive 连接可服务最大请求数默认1000仅当auth-keepalive 0时生效nginx.ingress.kubernetes.io/auth-keepalive-timeout空闲 keepalive 连接保持时长秒默认60nginx.ingress.kubernetes.io/auth-always-set-cookie是否始终设置认证请求返回的 cookie默认仅当状态码为 200/201/204/206/301/302/303/304/307/308 时设置nginx.ingress.kubernetes.io/auth-snippet追加到认证 location 的自定义 Nginx 配置片段必须与auth-url配合使用风险等级 Critical注意auth-keepalive在 HTTP/2 监听器下因 Lua subrequest 的限制而无法工作使用前应确认 ConfigMap 中的use-http2已关闭详见 annotations.md 中的提示。认证缓存与 keepalive 的源码级细节缓存auth-cache-duration的解析与校验在 authreq/main.go 的ValidCacheDuration中实现语法为“状态码 时长”序列时长支持ms/s/m/h/d/w/M/y单位对应 Nginx 官方语法ParseStringToCacheDurations保证至少返回默认值200 202 401 5m。这相当于为认证结果启用了proxy_cache_valid语义可显著降低认证服务的压力。keepalive 降级逻辑源码 authreq/main.go 显示一旦auth-keepalive、auth-keepalive-requests或auth-keepalive-timeout出现负值或auth-url的 host 部分包含$变量控制器都会把连接数强制回退到 0禁用 keepalive以避免生成无效的 Nginx upstream。keepalive 的 Lua 替代实现模板源码 template.go 的注释明确指出由于auth_request模块忽略 keepalive 指令nginx ticket #1579启用 keepalive 时控制器改用access_by_lua_block模拟同等功能。典型组合示例认证 登录页跳转 结果缓存apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-with-external-auth annotations: nginx.ingress.kubernetes.io/auth-url: https://auth.example.com/verify nginx.ingress.kubernetes.io/auth-method: POST nginx.ingress.kubernetes.io/auth-signin: https://auth.example.com/login?rd$scheme://$host$request_uri nginx.ingress.kubernetes.io/auth-signin-redirect-param: rd nginx.ingress.kubernetes.io/auth-response-headers: X-Auth-User, X-Auth-Groups nginx.ingress.kubernetes.io/auth-cache-key: $remote_user$http_authorization nginx.ingress.kubernetes.io/auth-cache-duration: 200 202 10m, 401 5m nginx.ingress.kubernetes.io/auth-keepalive: 50 nginx.ingress.kubernetes.io/auth-keepalive-requests: 500 nginx.ingress.kubernetes.io/auth-keepalive-timeout: 60 spec: ingressClassName: nginx rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: app-svc port: number: 80全局外部认证与灰度控制除了按 Ingress 逐条配置控制器还支持在 ConfigMap 中设置global-auth-url实现全局外部认证一旦设置所有 Ingress 请求默认都会先经过认证。若某条路由需要豁免则在其 Ingress 上显式添加nginx.ingress.kubernetes.io/enable-global-auth: false默认值为true。该机制的解析入口位于 internal/ingress/controller/template/configmap.go对应逻辑在shouldApplyGlobalAuthtemplate.go中体现仅当该 location未设置auth-url、全局地址非空且enable-global-auth为真时才套用全局认证。单元测试与端到端验证仓库为外部认证提供了充足的自动化保障可作为理解行为边界的参考注解解析单元测试internal/ingress/annotations/authreq/main_test.go 覆盖了 URL 合法性缺 scheme、非法 host、多级域名、auth-method、auth-response-headers、auth-cache-duration含“只有状态码无时长”“时长在状态码之前”等非法输入、keepalive 系列参数默认值及负值降级、以及auth-proxy-set-headers从 ConfigMap 读取头的场景。端到端测试test/e2e/annotations/auth.go 验证了“未配置认证时返回 200”“认证配置了无效 secret 时返回 503”“配置了认证但缺少 Authorization 头时返回 401”等真实行为。生产落地建议认证服务可用性是第一优先级外部认证是请求链路上的硬依赖认证服务不可用会直接导致 401/5xx 拦截流量。请为认证服务配置健康检查、限流与高可用并利用auth-cache-duration缓存认证结果以削减峰值请求。HTTPS 与证书生产环境auth-url应指向内部 HTTPS 服务认证服务返回 401 时携带的WWW-Authenticate挑战头会被原样透传可用于指导客户端弹窗行为。凭据泄露面控制原始Authorization头默认会透传到后端若后端无需明文凭据应使用auth-response-headers只透传认证服务返回的受控头。安全等级感知源码将auth-url标为高风险AnnotationRiskHigh、auth-snippet标为 Critical。若控制器开启了annotations-risk-level校验见 annotations-risk.md高/危风险注解的启用需要相应的安全配置放行切勿将敏感认证配置随意授予不可信用户。优先使用内部认证服务本文示例使用公网 httpbin 仅用于演示链路真实环境应部署在集群内避免把流量和凭据发给第三方。小结通过nginx.ingress.kubernetes.io/auth-urlIngress NGINX Controller 把“认证”与“路由”解耦鉴权逻辑完全由外部服务裁决控制器只负责在auth_request子请求失败时拦截、成功时放行并将认证结果响应头、cookie按需透传。本文的“无凭据 401 → 正确凭据 200 → 错误凭据 401”三段式验证配合auth-cache-*、auth-keepalive-*、auth-signin等扩展参数已经覆盖了从最小可用配置到生产级外部认证方案的完整链路。若需要进一步了解全局认证配置可查阅 configmap.md 中 global-auth-url 一节。【免费下载链接】ingress-nginxIngress NGINX Controller for Kubernetes项目地址: https://gitcode.com/GitHub_Trending/in/ingress-nginx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
