Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_auth_basic_module.xml @ 1878:127ae107e5a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed clause about shared memory and Windows versions with ASLR. Starting with nginx 1.9.0 shared memory can be used on Windows versions with address space layout randomization.
author Maxim Dounin <mdounin@mdounin.ru>
date Mon, 26 Dec 2016 19:38:06 +0300
parents a7974b8d2a23
children 66a30a380fba
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
580
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 494
diff changeset
3 <!--
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 494
diff changeset
4 Copyright (C) Igor Sysoev
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 494
diff changeset
5 Copyright (C) Nginx, Inc.
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 494
diff changeset
6 -->
be54c443235a Added copyright markers to documentation sources.
Ruslan Ermilov <ru@nginx.com>
parents: 494
diff changeset
7
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 <module name="Module ngx_http_auth_basic_module"
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 link="/en/docs/http/ngx_http_auth_basic_module.html"
589
764fbac1b8b4 Added document revision.
Ruslan Ermilov <ru@nginx.com>
parents: 580
diff changeset
12 lang="en"
1763
a7974b8d2a23 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1560
diff changeset
13 rev="8">
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15 <section id="summary">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
17 <para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 The <literal>ngx_http_auth_basic_module</literal> module allows
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 840
diff changeset
19 limiting access to resources by validating the user name and password
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 using the “HTTP Basic Authentication” protocol.
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 </para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22
494
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
23 <para>
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
24 Access can also be limited by
1763
a7974b8d2a23 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1560
diff changeset
25 <link doc="ngx_http_access_module.xml">address</link>, by the
a7974b8d2a23 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1560
diff changeset
26 <link doc="ngx_http_auth_request_module.xml">result of subrequest</link>,
a7974b8d2a23 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1560
diff changeset
27 or by <link doc="ngx_http_auth_jwt_module.xml">JWT</link>.
494
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
28 Simultaneous limitation of access by address and by password is controlled
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
29 by the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
30 </para>
244500f24783 - Cross linked ngx_http_access_module and ngx_http_auth_basic_module,
Ruslan Ermilov <ru@nginx.com>
parents: 351
diff changeset
31
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32 </section>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
34
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
35 <section id="example" name="Example Configuration">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37 <para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 <example>
351
a4fa80755eab Consistently strip initial offset in examples.
Ruslan Ermilov <ru@nginx.com>
parents: 315
diff changeset
39 location / {
a4fa80755eab Consistently strip initial offset in examples.
Ruslan Ermilov <ru@nginx.com>
parents: 315
diff changeset
40 auth_basic "closed site";
a4fa80755eab Consistently strip initial offset in examples.
Ruslan Ermilov <ru@nginx.com>
parents: 315
diff changeset
41 auth_basic_user_file conf/htpasswd;
a4fa80755eab Consistently strip initial offset in examples.
Ruslan Ermilov <ru@nginx.com>
parents: 315
diff changeset
42 }
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
43 </example>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
44 </para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
45
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
46 </section>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
47
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49 <section id="directives" name="Directives">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51 <directive name="auth_basic">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52 <syntax><value>string</value> | <literal>off</literal></syntax>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 <default>off</default>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54 <context>http</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 <context>server</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56 <context>location</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57 <context>limit_except</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 <para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 Enables validation of user name and password using the
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 “HTTP Basic Authentication” protocol.
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 The specified parameter is used as a <value>realm</value>.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 840
diff changeset
63 Parameter value can contain variables (1.3.10, 1.2.7).
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 840
diff changeset
64 The special value <literal>off</literal> allows cancelling the effect
784
7d15bd7fc58d The "auth_basic" directive now supports variables.
Ruslan Ermilov <ru@nginx.com>
parents: 655
diff changeset
65 of the <literal>auth_basic</literal> directive
7d15bd7fc58d The "auth_basic" directive now supports variables.
Ruslan Ermilov <ru@nginx.com>
parents: 655
diff changeset
66 inherited from the previous configuration level.
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 </para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69 </directive>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
71
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
72 <directive name="auth_basic_user_file">
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 <syntax><value>file</value></syntax>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 <default/>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 <context>http</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 <context>server</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 <context>location</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78 <context>limit_except</context>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 <para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 Specifies a file that keeps user names and passwords,
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 in the following format:
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
83 <example>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 # comment
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 name1:password1
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 name2:password2:comment
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 name3:password3
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 </example>
1560
dad3af7a1019 Documented variables support in auth_basic_user_file.
Ruslan Ermilov <ru@nginx.com>
parents: 990
diff changeset
89 The <value>file</value> name can contain variables.
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 </para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92 <para>
655
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
93 The following password types are supported:
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
94 <list type="bullet">
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
95
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
96 <listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
97 encrypted with the <c-func>crypt</c-func> function; can be generated using
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
98 the “<command>htpasswd</command>” utility from the Apache HTTP Server
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
99 distribution or the “<command>openssl passwd</command>” command;
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
100 </listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
101
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
102 <listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
103 hashed with the Apache variant of the MD5-based password algorithm (apr1);
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
104 can be generated with the same tools;
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
105 </listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
106
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
107 <listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
108 specified by the
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
109 “<literal>{</literal><value>scheme</value><literal>}</literal><value>data</value>”
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
110 syntax (1.0.3+) as described in
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
111 <link url="http://tools.ietf.org/html/rfc2307#section-5.3">RFC 2307</link>;
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
112 currently implemented schemes include <literal>PLAIN</literal> (an example one,
836
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
113 should not be used), <literal>SHA</literal> (1.3.13) (plain SHA-1
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
114 hashing, should not be used) and <literal>SSHA</literal> (salted SHA-1 hashing,
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
115 used by some software packages, notably OpenLDAP and Dovecot).
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
116 <note>
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
117 Support for <literal>SHA</literal> scheme was added only to aid
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
118 in migration from other web servers.
966
95c3c3bbf1ce Text review.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 840
diff changeset
119 It should not be used for new passwords, since unsalted SHA-1 hashing
836
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
120 that it employs is vulnerable to
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
121 <link url="http://en.wikipedia.org/wiki/Rainbow_attack">rainbow table</link>
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
122 attacks.
f563967a4f59 Auth basic: ${SHA} password scheme.
Ruslan Ermilov <ru@nginx.com>
parents: 784
diff changeset
123 </note>
655
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
124 </listitem>
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
125
93d2a54d247c Added information about supported password types.
Vladimir Homutov <vl@nginx.com>
parents: 589
diff changeset
126 </list>
315
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
127 </para>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
128
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129 </directive>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 </section>
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132
e00f8f8c0486 Translated ngx_http_access_module, ngx_http_addition_module,
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 </module>