Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_auth_request_module.xml @ 3090:27532d42102b default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the "rate" parameter of the "error_log" directive.
author Maxim Dounin <mdounin@mdounin.ru>
date Sun, 16 Jun 2024 06:55:30 +0300
parents 9eadb98ec770
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
971
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
2
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
3 <!--
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
4 Copyright (C) Maxim Dounin
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
5 Copyright (C) Nginx, Inc.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
6 -->
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
7
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
9
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
10 <module name="Module ngx_http_auth_request_module"
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
11 link="/en/docs/http/ngx_http_auth_request_module.html"
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
12 lang="en"
3043
9eadb98ec770 Free nginx: removed commercial version documentation.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1906
diff changeset
13 rev="6">
971
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
14
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
15 <section id="summary">
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
16
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
17 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
18 The <literal>ngx_http_auth_request_module</literal> module (1.5.4+) implements
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
19 client authorization based on the result of a subrequest.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
20 If the subrequest returns a 2xx response code, the access is allowed.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
21 If it returns 401 or 403,
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
22 the access is denied with the corresponding error code.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
23 Any other response code returned by the subrequest is considered an error.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
24 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
25
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
26 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
27 For the 401 error, the client also receives the
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
28 <header>WWW-Authenticate</header> header from the subrequest response.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
29 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
30
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
31 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
32 This module is not built by default, it should be enabled with the
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
33 <literal>--with-http_auth_request_module</literal>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
34 configuration parameter.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
35 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
36
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
37 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
38 The module may be combined with
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
39 other access modules, such as
3043
9eadb98ec770 Free nginx: removed commercial version documentation.
Maxim Dounin <mdounin@mdounin.ru>
parents: 1906
diff changeset
40 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> and
971
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
41 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>,
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
42 via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
43 <note>
1371
5475304b61ad Updated note about caching in the ngx_http_auth_request module.
Vladimir Homutov <vl@nginx.com>
parents: 998
diff changeset
44 Before version 1.7.3, responses to authorization subrequests could not be cached
998
726ce61dc10d Auth request: paraphrased a note.
Ruslan Ermilov <ru@nginx.com>
parents: 971
diff changeset
45 (using <link doc="ngx_http_proxy_module.xml" id="proxy_cache"/>,
726ce61dc10d Auth request: paraphrased a note.
Ruslan Ermilov <ru@nginx.com>
parents: 971
diff changeset
46 <link doc="ngx_http_proxy_module.xml" id="proxy_store"/>, etc.).
971
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
47 </note>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
48 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
49
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
50 </section>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
51
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
52
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
53 <section id="example" name="Example Configuration">
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
54
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
55 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
56 <example>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
57 location /private/ {
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
58 auth_request /auth;
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
59 ...
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
60 }
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
61
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
62 location = /auth {
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
63 proxy_pass ...
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
64 proxy_pass_request_body off;
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
65 proxy_set_header Content-Length "";
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
66 proxy_set_header X-Original-URI $request_uri;
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
67 }
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
68 </example>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
69 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
70
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
71 </section>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
72
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
73
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
74 <section id="directives" name="Directives">
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
75
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
76 <directive name="auth_request">
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
77 <syntax><value>uri</value> | <literal>off</literal></syntax>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
78 <default>off</default>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
79 <context>http</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
80 <context>server</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
81 <context>location</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
82
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
83 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
84 Enables authorization based on the result of a subrequest and sets
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
85 the URI to which the subrequest will be sent.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
86 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
87
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
88 </directive>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
89
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
90
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
91 <directive name="auth_request_set">
1906
e7a721d63544 Added variable sign in auth_request_set.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1763
diff changeset
92 <syntax><value>$variable</value> <value>value</value></syntax>
971
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
93 <default/>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
94 <context>http</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
95 <context>server</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
96 <context>location</context>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
97
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
98 <para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
99 Sets the request <value>variable</value> to the given
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
100 <value>value</value> after the authorization request completes.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
101 The value may contain variables from the authorization request,
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
102 such as <var>$upstream_http_*</var>.
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
103 </para>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
104
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
105 </directive>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
106
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
107 </section>
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
108
6316a7579448 Documented the "ngx_http_auth_request" module.
Vladimir Homutov <vl@nginx.com>
parents:
diff changeset
109 </module>