Authentication Based on Subrequest Result (original) (raw)

  1. Home
  2. F5 NGINX Plus
  3. Admin Guide
  4. Security Controls Authentication Based on Subrequest Result

NGINX and F5 NGINX Plus can authenticate each request to your website with an external server or service. To perform authentication, NGINX makes an HTTP subrequest to an external server where it is verified. Such type of authentication allows implementing various authentication schemes, such as multifactor authentication, or allows implementing LDAP or OAuth authentication.

Subrequest Response Codes:

Configuring NGINX and NGINX Plus

  1. Make sure your NGINX Open Source is compiled with the with-http_auth_request_module configuration option. Run this command and verify that the output includes --with-http_auth_request_module:
nginx -V 2>&1 | grep -- 'http_auth_request_module'  
nginx -V 2>&1 | grep -- 'http_auth_request_module'

Skip this step for NGINX Plus as it already includes the auth_request module. 2. In the location that requires request authentication, specify the auth_request directive and specify an internal location where an authorization subrequest will be forwarded to:
nginx 

location /private/ {  
    auth_request /auth;  
    #...  
}  
location /private/ {  
    auth_request /auth;  
    #...  
}

Here, for each request to /private, a subrequest to the internal /auth location will be made. 3. Specify an internal location and the proxy_pass directive inside this location that will proxy authentication subrequests to an authentication server or service:
nginx 

location = /auth {  
    internal;  
    proxy_pass http://auth-server;  
    #...  
}  
location = /auth {  
    internal;  
    proxy_pass http://auth-server;  
    #...  
}
  1. As the request body is discarded for authentication subrequests, set the proxy_pass_request_body directive to off and also set the Content-Length header to a null string:
    nginx
location = /auth {  
    internal;  
    proxy_pass              http://auth-server;  
    proxy_pass_request_body off;  
    proxy_set_header        Content-Length "";  
    #...  
}  
location = /auth {  
    internal;  
    proxy_pass              http://auth-server;  
    proxy_pass_request_body off;  
    proxy_set_header        Content-Length "";  
    #...  
}
  1. Pass the full original request URI with arguments with the proxy_set_header directive:
    nginx
location = /auth {  
    internal;  
    proxy_pass              http://auth-server;  
    proxy_pass_request_body off;  
    proxy_set_header        Content-Length "";  
    proxy_set_header        X-Original-URI $request_uri;  
}  
location = /auth {  
    internal;  
    proxy_pass              http://auth-server;  
    proxy_pass_request_body off;  
    proxy_set_header        Content-Length "";  
    proxy_set_header        X-Original-URI $request_uri;  
}
  1. As an option, you can set a variable value basing on the result of the subrequest with the auth_request_set directive:
    nginx
location /private/ {  
    auth_request        /auth;  
    auth_request_set <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>a</mi><mi>u</mi><mi>t</mi><msub><mi>h</mi><mi>s</mi></msub><mi>t</mi><mi>a</mi><mi>t</mi><mi>u</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">auth_status </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8444em;vertical-align:-0.15em;"></span><span class="mord mathnormal">a</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord"><span class="mord mathnormal">h</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">s</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">u</span><span class="mord mathnormal">s</span></span></span></span>upstream_status;  
}  
location /private/ {  
    auth_request        /auth;  
    auth_request_set <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>a</mi><mi>u</mi><mi>t</mi><msub><mi>h</mi><mi>s</mi></msub><mi>t</mi><mi>a</mi><mi>t</mi><mi>u</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">auth_status </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8444em;vertical-align:-0.15em;"></span><span class="mord mathnormal">a</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord"><span class="mord mathnormal">h</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">s</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">u</span><span class="mord mathnormal">s</span></span></span></span>upstream_status;  
}

This example sums up the previous steps into one configuration:

nginx

http {
    #...
    server {
    #...
        location /private/ {
            auth_request     /auth;
            auth_request_set <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>a</mi><mi>u</mi><mi>t</mi><msub><mi>h</mi><mi>s</mi></msub><mi>t</mi><mi>a</mi><mi>t</mi><mi>u</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">auth_status </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8444em;vertical-align:-0.15em;"></span><span class="mord mathnormal">a</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord"><span class="mord mathnormal">h</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">s</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">u</span><span class="mord mathnormal">s</span></span></span></span>upstream_status;
        }

        location = /auth {
            internal;
            proxy_pass              http://auth-server;
            proxy_pass_request_body off;
            proxy_set_header        Content-Length "";
            proxy_set_header        X-Original-URI $request_uri;
        }
    }
}
http {
    #...
    server {
    #...
        location /private/ {
            auth_request     /auth;
            auth_request_set <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>a</mi><mi>u</mi><mi>t</mi><msub><mi>h</mi><mi>s</mi></msub><mi>t</mi><mi>a</mi><mi>t</mi><mi>u</mi><mi>s</mi></mrow><annotation encoding="application/x-tex">auth_status </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.8444em;vertical-align:-0.15em;"></span><span class="mord mathnormal">a</span><span class="mord mathnormal">u</span><span class="mord mathnormal">t</span><span class="mord"><span class="mord mathnormal">h</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.1514em;"><span style="top:-2.55em;margin-left:0em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">s</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.15em;"><span></span></span></span></span></span></span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">t</span><span class="mord mathnormal">u</span><span class="mord mathnormal">s</span></span></span></span>upstream_status;
        }

        location = /auth {
            internal;
            proxy_pass              http://auth-server;
            proxy_pass_request_body off;
            proxy_set_header        Content-Length "";
            proxy_set_header        X-Original-URI $request_uri;
        }
    }
}