<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_auth_basic_module"
        link="/ru/docs/http/ngx_http_auth_basic_module.html"
        lang="ru"
        rev="12">

<section id="summary">

<para>
Модуль <literal>ngx_http_auth_basic_module</literal> позволяет
ограничить доступ к ресурсам с проверкой имени и пароля пользователя
по протоколу “HTTP Basic Authentication”.
</para>

<para>
Ограничить доступ можно также по
<link doc="ngx_http_access_module.xml">адресу</link> или по
<link doc="ngx_http_auth_request_module.xml">результату подзапроса</link>.
Одновременное ограничение доступа по адресу и паролю управляется
директивой <link doc="ngx_http_core_module.xml" id="satisfy"/>.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
location / {
    auth_basic           "closed site";
    auth_basic_user_file conf/htpasswd;
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="auth_basic">
<syntax><value>строка</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>limit_except</context>

<para>
Включает проверку имени и пароля пользователя по протоколу
“HTTP Basic Authentication”.
Заданный параметр используется в качестве <value>realm</value>.
В значении параметра допустимо использование переменных (1.3.10, 1.2.7).
Специальное значение <literal>off</literal> отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы <literal>auth_basic</literal>.
</para>

</directive>


<directive name="auth_basic_user_file">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>limit_except</context>

<para>
Задаёт файл, в котором хранятся имена и пароли пользователей.
Формат файла следующий:
<example>
# комментарий
имя1:пароль1
имя2:пароль2:комментарий
имя3:пароль3
</example>
В имени файла можно использовать переменные.
</para>

<para>
Пароли должны быть зашифрованы
<link url="https://ru.wikipedia.org/wiki/Crypt_(C)">функцией crypt()</link>.
Доступны все методы хэширования паролей, поддерживаемые операционной системой.
В частности, распространены следующие методы хэширования:

<list type="bullet">

<listitem>
основанный на MD5 метод, <literal>$1$</literal>;
</listitem>

<listitem>
основанный на SHA256 метод, <literal>$5$</literal>;
</listitem>

<listitem>
основанный на SHA512 метод, <literal>$6$</literal>.
</listitem>

</list>
</para>

<para>
Кроме того, поддерживаются следующие кросс-платформенные типы паролей:
<list type="bullet">

<listitem>
хэшированные с помощью основанного на MD5 метода по версии Apache
(<literal>$apr1$</literal>);
</listitem>

<listitem>
заданные согласно синтаксису
“<literal>{</literal><value>схема</value><literal>}</literal><value>данные</value>”
(1.0.3+) как описано в
<link url="https://datatracker.ietf.org/doc/html/rfc2307#section-5.3">RFC 2307</link>;
в настоящий момент реализованы схемы <literal>PLAIN</literal> (в качестве
примера, не следует применять), <literal>SHA</literal> (1.3.13) (простое SHA-1
хэширование, не следует применять) и <literal>SSHA</literal> (SHA-1 хэширование
с солью, также небезопасно по современным стандартам).
</listitem>

</list>
</para>

<para>
Хэши паролей для распространнённых методов хэширования могут быть сгенерированы
с помощью команды “<command>openssl passwd</command>”, например:

<example>
$ openssl passwd -apr1 secret
$apr1$x/muFo1c$zwUN24M2TEq.6wg0AZacn0
</example>
<example>
$ openssl passwd -6 secret
$6$FjZ1ss8ytcGmrGFY$1fopTJLuLUGCRlv2YcRPIsZk9uaD9NBOGcKsUay/BLV3RR1ol0ONS08oPTVqA4XBkZ44M7OL4K6NjP9xPKShP0
</example>
</para>

<para>
При выборе метода хэширования паролей следует учитывать, что
HTTP Basic Authentication подразумевает проверку пароля при каждом запросе.
</para>

</directive>

</section>

</module>