Deep Dive into NGINX auth_request Subrequest Configuration
Configure auth_request with internal subrequest, POST method, no body, proper headers, and error_page to fail-closed.
Patch NGINX auth.conf to include the recommended directives and test subrequest behavior.
Summary
The post dissects the auth_request directive and the subrequest lifecycle. It shows that the main request is paused, an internal subrequest to /auth is made, and the status of that subrequest determines whether the main request proceeds. The auth.conf file is carefully crafted: it uses internal; to restrict /auth to subrequests, proxy_method POST with proxy_pass_request_body off to avoid sending the body, and forwards original request details via X‑Original‑* headers. Proxy_buffering is disabled for low latency, proxy_http_version 1.1 with Connection "" enables keep‑alive, and timeouts are set to 5s connect, 10s send/read. Error pages for 502/503/504 redirect to @auth_unavailable. The configuration also includes proxy_next_upstream settings to retry on errors.
The article explains why each directive matters: internal; prevents external access, POST ensures consistent logging, no body avoids large uploads, X‑Original headers preserve original request context, and keep‑alive reduces connection overhead. The author stresses that the subrequest is fully finished before the upstream is contacted, so latency is additive.
By following this configuration, the gateway achieves a fail‑closed posture and low‑latency authentication.
Key takeaways include the importance of internal subrequests, proper header forwarding, and efficient proxy settings.
Key changes
- Use internal; to restrict /auth to subrequests
- Set proxy_method POST and proxy_pass_request_body off
- Forward X-Original-URI, X-Original-Method, X-Original-Host, X-Original-URL, X-Request-ID, X-Tenant-ID
- Disable proxy_buffering for low latency
- Set proxy_http_version 1.1 and Connection "" for keep‑alive
- Configure proxy_connect_timeout 5s, proxy_send_timeout 10s, proxy_read_timeout 10s
- Set error_page 502 503 504 = @auth_unavailable
- Use proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504