Nginx ngx_http_auth_request_module Scope and Build Configuration
The ngx_http_auth_request_module (available in Nginx 1.5.4+) provides client authorization by executing an internal subrequest to a designated URI before allowing access to a protected resource. Nginx does not build this module by default; it should be enabled with the --with-http_auth_request_module configuration parameter, as detailed in the official Nginx ngx_http_auth_request_module documentation.
Subrequest Mechanics and Status Code Evaluation
When authorization is enabled within a context, Nginx dispatches a subrequest to the specified authentication URI. Client authorization is determined strictly by the HTTP status code returned by that subrequest:
- 2xx Success: If the subrequest returns an HTTP 2xx response code, authorization succeeds, and access is allowed.
- 401 Unauthorized: If the subrequest returns HTTP 401, access is denied with a 401 status code. Nginx forwards the
WWW-Authenticateheader from the subrequest response to the client. - 403 Forbidden: If the subrequest returns HTTP 403, access is denied with a 403 status code.
- Other Codes: Any response code outside of 2xx, 401, or 403 is treated by Nginx as an error.
Directive Syntax and Context Reference
The module introduces two primary directives, both valid within the http, server, and location configuration contexts:
auth_request uri | off;(Default:off): Enables authorization based on subrequest evaluation and sets the target URI to which the subrequest will be sent.auth_request_set $variable value;(Default: none): Sets a request variable to a designated value after the authorization subrequest completes. The value can capture variables populated by the authorization subrequest, including upstream response headers using$upstream_http_*.
Access Module Combination and Subrequest Caching
The authorization module can be combined with other access modules—including ngx_http_access_module, ngx_http_auth_basic_module, and ngx_http_auth_jwt_module—via the satisfy directive. Regarding subrequest performance, versions prior to Nginx 1.7.3 could not cache responses to authorization subrequests using proxy_cache, proxy_store, etc.; caching support is available starting in version 1.7.3.
Documented Configuration Example
The official documentation outlines the following baseline pattern for delegating authentication to a proxy location:
location /private/ {
auth_request /auth;
...
}
location = /auth {
proxy_pass ...;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
}
Text version of the diagrams
- Auth Request Status Outcomes: 2xx Success — Protected access allowed; 401 Response — Denied; header forwarded; 403 / Other — Denied or treated as error
- Two Directive Roles: auth_request — Sets subrequest URI; auth_request_set — Sets request variable; $upstream_http_* — Reads auth response data
Research Method and Limitations
This technical explainer was prepared exclusively from the visible text of the official Nginx ngx_http_auth_request_module documentation retrieved on 2026-09-17. It contains no lab benchmarks, performance testing, synthetic load data, or unverified custom proxy scripts. Competing search results were unavailable during retrieval, so comparative coverage limits remain unobserved.
