Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_auth_request_module.xml @ 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
children 726ce61dc10d
comparison
equal deleted inserted replaced
970:051de14a6e79 971:6316a7579448
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Maxim Dounin
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_http_auth_request_module"
11 link="/en/docs/http/ngx_http_auth_request_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_http_auth_request_module</literal> module (1.5.4+) implements
19 client authorization based on the result of a subrequest.
20 If the subrequest returns a 2xx response code, the access is allowed.
21 If it returns 401 or 403,
22 the access is denied with the corresponding error code.
23 Any other response code returned by the subrequest is considered an error.
24 </para>
25
26 <para>
27 For the 401 error, the client also receives the
28 <header>WWW-Authenticate</header> header from the subrequest response.
29 </para>
30
31 <para>
32 This module is not built by default, it should be enabled with the
33 <literal>--with-http_auth_request_module</literal>
34 configuration parameter.
35 </para>
36
37 <para>
38 The module may be combined with
39 other access modules, such as
40 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> and
41 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>,
42 via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
43 <note>
44 Currently, it is not possible to use
45 <link doc="ngx_http_proxy_module.xml" id="proxy_cache"/> and
46 <link doc="ngx_http_proxy_module.xml" id="proxy_store"/>
47 (<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_cache"/> and
48 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_store"/>)
49 for requests initiated by the
50 <literal>ngx_http_auth_request_module</literal> module.
51 </note>
52 </para>
53
54 </section>
55
56
57 <section id="example" name="Example Configuration">
58
59 <para>
60 <example>
61 location /private/ {
62 auth_request /auth;
63 ...
64 }
65
66 location = /auth {
67 proxy_pass ...
68 proxy_pass_request_body off;
69 proxy_set_header Content-Length "";
70 proxy_set_header X-Original-URI $request_uri;
71 }
72 </example>
73 </para>
74
75 </section>
76
77
78 <section id="directives" name="Directives">
79
80 <directive name="auth_request">
81 <syntax><value>uri</value> | <literal>off</literal></syntax>
82 <default>off</default>
83 <context>http</context>
84 <context>server</context>
85 <context>location</context>
86
87 <para>
88 Enables authorization based on the result of a subrequest and sets
89 the URI to which the subrequest will be sent.
90 </para>
91
92 </directive>
93
94
95 <directive name="auth_request_set">
96 <syntax><value>variable</value> <value>value</value></syntax>
97 <default/>
98 <context>http</context>
99 <context>server</context>
100 <context>location</context>
101
102 <para>
103 Sets the request <value>variable</value> to the given
104 <value>value</value> after the authorization request completes.
105 The value may contain variables from the authorization request,
106 such as <var>$upstream_http_*</var>.
107 </para>
108
109 </directive>
110
111 </section>
112
113 </module>