Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_auth_request_module.xml @ 971:6316a7579448
Documented the "ngx_http_auth_request" module.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Thu, 22 Aug 2013 17:23:42 +0400 |
parents | |
children | 726ce61dc10d |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_auth_request_module.xml @@ -0,0 +1,113 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Maxim Dounin + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_auth_request_module" + link="/en/docs/http/ngx_http_auth_request_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_auth_request_module</literal> module (1.5.4+) implements +client authorization based on the result of a subrequest. +If the subrequest returns a 2xx response code, the access is allowed. +If it returns 401 or 403, +the access is denied with the corresponding error code. +Any other response code returned by the subrequest is considered an error. +</para> + +<para> +For the 401 error, the client also receives the +<header>WWW-Authenticate</header> header from the subrequest response. +</para> + +<para> +This module is not built by default, it should be enabled with the +<literal>--with-http_auth_request_module</literal> +configuration parameter. +</para> + +<para> +The module may be combined with +other access modules, such as +<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> and +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>, +via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. +<note> +Currently, it is not possible to use +<link doc="ngx_http_proxy_module.xml" id="proxy_cache"/> and +<link doc="ngx_http_proxy_module.xml" id="proxy_store"/> +(<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_cache"/> and +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_store"/>) +for requests initiated by the +<literal>ngx_http_auth_request_module</literal> module. +</note> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +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; +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="auth_request"> +<syntax><value>uri</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables authorization based on the result of a subrequest and sets +the URI to which the subrequest will be sent. +</para> + +</directive> + + +<directive name="auth_request_set"> +<syntax><value>variable</value> <value>value</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the request <value>variable</value> to the given +<value>value</value> after the authorization request completes. +The value may contain variables from the authorization request, +such as <var>$upstream_http_*</var>. +</para> + +</directive> + +</section> + +</module>