<?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>