Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_auth_basic_module.xml @ 3099:9cfda14d0109 default tip
freenginx-1.27.4
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 03 Sep 2024 13:15:18 +0300 |
parents | aea3e104f11d |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Igor Sysoev Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_auth_basic_module" link="/en/docs/http/ngx_http_auth_basic_module.html" lang="en" rev="12"> <section id="summary"> <para> The <literal>ngx_http_auth_basic_module</literal> module allows limiting access to resources by validating the user name and password using the “HTTP Basic Authentication” protocol. </para> <para> Access can also be limited by <link doc="ngx_http_access_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> </section> <section id="example" name="Example Configuration"> <para> <example> location / { auth_basic "closed site"; auth_basic_user_file conf/htpasswd; } </example> </para> </section> <section id="directives" name="Directives"> <directive name="auth_basic"> <syntax><value>string</value> | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Enables validation of user name and password using the “HTTP Basic Authentication” protocol. The specified parameter is used as a <value>realm</value>. Parameter value can contain variables (1.3.10, 1.2.7). The special value <literal>off</literal> cancels the effect of the <literal>auth_basic</literal> directive inherited from the previous configuration level. </para> </directive> <directive name="auth_basic_user_file"> <syntax><value>file</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Specifies a file that keeps user names and passwords, in the following format: <example> # comment name1:password1 name2:password2:comment name3:password3 </example> The <value>file</value> name can contain variables. </para> <para> Passwords are expected to be encrypted by the <link url="https://en.wikipedia.org/wiki/Crypt_(C)">crypt() function</link>. All password hashing methods as supported by the OS can be used. In particular, the following <c-func>crypt</c-func> hashing methods are commonly available: <list type="bullet"> <listitem> MD5-based <c-func>crypt</c-func> method, <literal>$1$</literal>; </listitem> <listitem> SHA256-based <c-func>crypt</c-func> method, <literal>$5$</literal>; </listitem> <listitem> SHA512-based <c-func>crypt</c-func> method, <literal>$6$</literal>. </listitem> </list> </para> <para> Additionally, the following cross-platform password types are supported: <list type="bullet"> <listitem> hashed with the Apache variant of the MD5-based <c-func>crypt</c-func> method (<literal>$apr1$</literal>); </listitem> <listitem> specified by the “<literal>{</literal><value>scheme</value><literal>}</literal><value>data</value>” syntax (1.0.3+) as described in <link url="https://datatracker.ietf.org/doc/html/rfc2307#section-5.3">RFC 2307</link>; supported schemes are <literal>PLAIN</literal> (an example one, should not be used), <literal>SHA</literal> (1.3.13) (plain SHA-1 hashing, insecure and should not be used), and <literal>SSHA</literal> (salted SHA-1 hashing, also insecure by today's standards). </listitem> </list> </para> <para> Password hashes for common hashing methods can be generated using the “<command>openssl passwd</command>” command, for example: <example> $ openssl passwd -apr1 secret $apr1$x/muFo1c$zwUN24M2TEq.6wg0AZacn0 </example> <example> $ openssl passwd -6 secret $6$FjZ1ss8ytcGmrGFY$1fopTJLuLUGCRlv2YcRPIsZk9uaD9NBOGcKsUay/BLV3RR1ol0ONS08oPTVqA4XBkZ44M7OL4K6NjP9xPKShP0 </example> </para> <para> Note that HTTP Basic Authentication implies password validation on each request, and password hashing method should be choosen with this in mind. </para> </directive> </section> </module>