Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_auth_basic_module.xml @ 3095:aea3e104f11d
Reworked auth_basic_user_file documentation.
Some extra details about crypt(3) are provided, emphasizing modular
crypt() usage and commonly available password hashing methods. Also,
added some examples on how to use "openssl passwd" to generate password
hashes, made it clear that {SSHA} passwords are not secure now, and
added a note about passwords being validated on each request.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Sat, 31 Aug 2024 05:19:25 +0300 |
parents | 9eadb98ec770 |
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>