ngx_http_auth_request_module

Authorize requests with a subrequest to an external service

compiled inBSD-2-Clausesource docs

Overview

ngx_http_auth_request_module implements client authorization based on the result of a subrequest. Before serving a protected location nginx sends a subrequest to the configured URI: a 2xx response allows access, 401 or 403 denies it with the same code, and any other code is treated as an error.

For a 401 the client also receives the WWW-Authenticate header from the subrequest response. auth_request_set copies values from the authorization response, such as $upstream_http_* headers, into request variables for use in later proxying. The module appeared in 1.5.4 and can be combined with ngx_http_access_module and ngx_http_auth_basic_module through the satisfy directive.

It is an official nginx module and is not built by default upstream, so it needs the --with-http_auth_request_module configure parameter. A typical use is putting single sign-on or an OAuth2 proxy in front of internal applications that have no authentication of their own.

Key directives

auth_requestEnables subrequest authorization and sets the URI the subrequest is sent to, default off.
auth_request_setSets a request variable after the authorization request completes; the value may use $upstream_http_*.
response code handling2xx allows access, 401 or 403 denies it with that code, any other code is considered an error.
satisfyCombines auth_request with access and auth_basic checks so any or all of them must pass.

Example

nginx.conf
location /private/ { auth_request /auth; # pass the identity returned by the auth service to the backend auth_request_set $auth_user $upstream_http_x_auth_user; proxy_set_header X-Auth-User $auth_user; proxy_pass http://app; } location = /auth { internal; proxy_pass http://auth-service/verify; proxy_pass_request_body off; proxy_set_header Content-Length ""; proxy_set_header X-Original-URI $request_uri; }

Availability

Compiled into every n.wtf nginx binary. Install nginx-extras and the directives above work out of the box, no load_module line needed.