Mercurial > hg > nginx-site

changeset 971:6316a7579448

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the "ngx_http_auth_request" module.
author Vladimir Homutov <vl@nginx.com>
date Thu, 22 Aug 2013 17:23:42 +0400
parents 051de14a6e79
children dee46eeb0f8c
files xml/en/GNUmakefile xml/en/docs/http/ngx_http_access_module.xml xml/en/docs/http/ngx_http_auth_basic_module.xml xml/en/docs/http/ngx_http_auth_request_module.xml xml/en/docs/http/ngx_http_core_module.xml xml/en/docs/index.xml xml/en/index.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_access_module.xml xml/ru/docs/http/ngx_http_auth_basic_module.xml xml/ru/docs/http/ngx_http_auth_request_module.xml xml/ru/docs/http/ngx_http_core_module.xml xml/ru/docs/index.xml xml/ru/index.xml
diffstat 14 files changed, 271 insertions(+), 24 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -35,6 +35,7 @@ REFS =									\
 		http/ngx_http_access_module				\
 		http/ngx_http_addition_module				\
 		http/ngx_http_auth_basic_module				\
+		http/ngx_http_auth_request_module			\
 		http/ngx_http_autoindex_module				\
 		http/ngx_http_browser_module				\
 		http/ngx_http_charset_module				\
--- a/xml/en/docs/http/ngx_http_access_module.xml
+++ b/xml/en/docs/http/ngx_http_access_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_access_module"
         link="/en/docs/http/ngx_http_access_module.html"
         lang="en"
-        rev="2">
+        rev="3">
 
 <section id="summary">
 
@@ -21,7 +21,8 @@ limiting access to certain client addres
 
 <para>
 Access can also be limited by
-<link doc="ngx_http_auth_basic_module.xml">password</link>.
+<link doc="ngx_http_auth_basic_module.xml">password</link> or by the
+<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>.
 Simultaneous limitation of access by address and by password is controlled
 by the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
 </para>
--- a/xml/en/docs/http/ngx_http_auth_basic_module.xml
+++ b/xml/en/docs/http/ngx_http_auth_basic_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_auth_basic_module"
         link="/en/docs/http/ngx_http_auth_basic_module.html"
         lang="en"
-        rev="5">
+        rev="6">
 
 <section id="summary">
 
@@ -22,7 +22,8 @@ using the “HTTP Basic Authentication” protocol.
 
 <para>
 Access can also be limited by
-<link doc="ngx_http_auth_basic_module.xml">address</link>.
+<link doc="ngx_http_auth_basic_module.xml">address</link> or by the
+<link doc="ngx_http_auth_request_module.xml">result of subrequest</link>.
 Simultaneous limitation of access by address and by password is controlled
 by the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
 </para>
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>
--- a/xml/en/docs/http/ngx_http_core_module.xml
+++ b/xml/en/docs/http/ngx_http_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_core_module"
         link="/en/docs/http/ngx_http_core_module.html"
         lang="en"
-        rev="22">
+        rev="23">
 
 <section id="directives" name="Directives">
 
@@ -2037,10 +2037,11 @@ If a URI has to be modified, the
 <context>location</context>
 
 <para>
-Allows access if both (<literal>all</literal>) or at least one
+Allows access if all (<literal>all</literal>) or at least one
 (<literal>any</literal>) of the
-<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
-or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
+<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>,
+<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> or
+<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>
 modules allow access.
 </para>
 
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -171,6 +171,11 @@ ngx_http_auth_basic_module</link>
 </listitem>
 
 <listitem>
+<link doc="http/ngx_http_auth_request_module.xml">
+ngx_http_auth_request_module</link>
+</listitem>
+
+<listitem>
 <link doc="http/ngx_http_autoindex_module.xml">
 ngx_http_autoindex_module</link>
 </listitem>
--- a/xml/en/index.xml
+++ b/xml/en/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx"
          link="/en/"
          lang="en"
-         rev="11">
+         rev="12">
 
 
 <section>
@@ -151,9 +151,11 @@ different functions</link> depending on 
 
 <listitem>
 Access control based on
-<link doc="docs/http/ngx_http_access_module.xml">client IP address</link>
-and <link doc="docs/http/ngx_http_auth_basic_module.xml">HTTP
-Basic authentication</link>;
+<link doc="docs/http/ngx_http_access_module.xml">client IP address</link>,
+<link doc="docs/http/ngx_http_auth_basic_module.xml">by password (HTTP
+Basic authentication)</link> and by the
+<link doc="docs/http/ngx_http_auth_request_module.xml">result of
+subrequest</link>;
 </listitem>
 
 <listitem>
--- a/xml/ru/GNUmakefile
+++ b/xml/ru/GNUmakefile
@@ -26,6 +26,7 @@ REFS =									\
 		http/ngx_http_access_module				\
 		http/ngx_http_addition_module				\
 		http/ngx_http_auth_basic_module				\
+		http/ngx_http_auth_request_module			\
 		http/ngx_http_autoindex_module				\
 		http/ngx_http_browser_module				\
 		http/ngx_http_charset_module				\
--- a/xml/ru/docs/http/ngx_http_access_module.xml
+++ b/xml/ru/docs/http/ngx_http_access_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_access_module"
         link="/ru/docs/http/ngx_http_access_module.html"
         lang="ru"
-        rev="2">
+        rev="3">
 
 <section id="summary">
 
@@ -21,7 +21,8 @@
 
 <para>
 Ограничить доступ можно также по
-<link doc="ngx_http_auth_basic_module.xml">паролю</link>.
+<link doc="ngx_http_auth_basic_module.xml">паролю</link> или по
+<link doc="ngx_http_auth_basic_module.xml">результату подзапроса</link>.
 Одновременное ограничение доступа по адресу и паролю управляется
 директивой <link doc="ngx_http_core_module.xml" id="satisfy"/>.
 </para>
--- a/xml/ru/docs/http/ngx_http_auth_basic_module.xml
+++ b/xml/ru/docs/http/ngx_http_auth_basic_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_auth_basic_module"
         link="/ru/docs/http/ngx_http_auth_basic_module.html"
         lang="ru"
-        rev="5">
+        rev="6">
 
 <section id="summary">
 
@@ -22,7 +22,8 @@
 
 <para>
 Ограничить доступ можно также по
-<link doc="ngx_http_access_module.xml">адресу</link>.
+<link doc="ngx_http_access_module.xml">адресу</link> или по
+<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>.
 Одновременное ограничение доступа по адресу и паролю управляется
 директивой <link doc="ngx_http_core_module.xml" id="satisfy"/>.
 </para>
new file mode 100644
--- /dev/null
+++ b/xml/ru/docs/http/ngx_http_auth_request_module.xml
@@ -0,0 +1,112 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Maxim Dounin
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Модуль ngx_http_auth_request_module"
+        link="/ru/docs/http/ngx_http_auth_request_module.html"
+        lang="ru"
+        rev="1">
+
+<section id="summary">
+
+<para>
+Модуль <literal>ngx_http_auth_request_module</literal> (1.5.4+) предоставляет
+возможность авторизации клиента, основанной на результате подзапроса.
+Если подзапрос возвращает код ответа 2xx, доступ разрешается.
+Если 401 или 403 — доступ запрещается с соответствующим кодом ошибки.
+Любой другой код ответа, возвращаемый подзапросом, считается ошибкой.
+</para>
+
+<para>
+При ошибке 401 клиенту также передаётся заголовок
+<header>WWW-Authenticate</header> из ответа подзапроса.
+</para>
+
+<para>
+По умолчанию этот модуль не собирается, его сборку необходимо
+разрешить с помощью конфигурационного параметра
+<literal>--with-http_auth_request_module</literal>.
+</para>
+
+<para>
+Модуль может быть
+скомбинирован с другими модулями доступа, такими как
+<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> и
+<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>,
+с помощью директивы <link doc="ngx_http_core_module.xml" id="satisfy"/>.
+<note>
+В данный момент директивы
+<link doc="ngx_http_proxy_module.xml" id="proxy_cache"/> и
+<link doc="ngx_http_proxy_module.xml" id="proxy_store"/>
+(<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_cache"/> и
+<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_store"/>)
+невозможно использовать для обработки запросов, исходящих от модуля
+<literal>ngx_http_auth_request_module</literal>.
+</note>
+</para>
+
+</section>
+
+
+<section id="example" name="Пример конфигурации">
+
+<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="Директивы">
+
+<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>
+Включает авторизацию, основанную на результате выполнения подзапроса,
+и задаёт URI, на который будет отправлен подзапрос.
+</para>
+
+</directive>
+
+
+<directive name="auth_request_set">
+<syntax><value>переменная</value> <value>значение</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Устанавливает <value>переменную</value> в запросе в заданное
+<value>значение</value> после завершения запроса авторизации.
+Значение может содержать переменные из запроса авторизации,
+например, <var>$upstream_http_*</var>.
+</para>
+
+</directive>
+
+</section>
+
+</module>
--- a/xml/ru/docs/http/ngx_http_core_module.xml
+++ b/xml/ru/docs/http/ngx_http_core_module.xml
@@ -10,7 +10,7 @@
 <module name="Модуль ngx_http_core_module"
         link="/ru/docs/http/ngx_http_core_module.html"
         lang="ru"
-        rev="22">
+        rev="23">
 
 <section id="directives" name="Директивы">
 
@@ -2033,10 +2033,11 @@ location /i/ {
 <context>location</context>
 
 <para>
-Разрешает доступ, если оба (<literal>all</literal>)
+Разрешает доступ, если все (<literal>all</literal>)
 или хотя бы один (<literal>any</literal>) из модулей
-<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
-и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>
+<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>,
+<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> или
+<link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>
 разрешают доступ.
 </para>
 
--- a/xml/ru/docs/index.xml
+++ b/xml/ru/docs/index.xml
@@ -159,6 +159,11 @@ ngx_http_auth_basic_module</link>
 </listitem>
 
 <listitem>
+<link doc="http/ngx_http_auth_request_module.xml">
+ngx_http_auth_request_module</link>
+</listitem>
+
+<listitem>
 <link doc="http/ngx_http_autoindex_module.xml">
 ngx_http_autoindex_module</link>
 </listitem>
--- a/xml/ru/index.xml
+++ b/xml/ru/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx"
          link="/ru/"
          lang="ru"
-         rev="11">
+         rev="12">
 
 
 <section>
@@ -152,9 +152,11 @@ rewrite-модуль:
 
 <listitem>
 Ограничение доступа в зависимости от
-<link doc="docs/http/ngx_http_access_module.xml">адреса клиента</link>
-и <link doc="docs/http/ngx_http_auth_basic_module.xml">по паролю
-(HTTP Basic аутентификация)</link>;
+<link doc="docs/http/ngx_http_access_module.xml">адреса клиента</link>,
+<link doc="docs/http/ngx_http_auth_basic_module.xml">по паролю
+(HTTP Basic аутентификация)</link> и по
+<link doc="docs/http/ngx_http_auth_request_module.xml">результату
+подзапроса</link>;
 </listitem>
 
 <listitem>