<?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="10">

<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_auth_jwt_module.xml">JWT</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>
Поддерживаются следующие типы паролей:
<list type="bullet">

<listitem>
зашифрованные функцией <c-func>crypt</c-func>; могут быть созданы
с помощью утилиты “<command>htpasswd</command>” из дистрибутива HTTP-сервера
Apache или команды “<command>openssl passwd</command>”;
</listitem>

<listitem>
хэшированные с помощью алгоритма, основанного на MD5, по версии Apache (apr1);
могут быть созданы теми же инструментами;
</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 хэширование
с солью, используется в некоторых программах, в частности OpenLDAP
и Dovecot).
<note>
Поддержка схемы <literal>SHA</literal> была добавлена лишь для облегчения
процесса миграции файлов паролей с других веб-серверов.
Её не следует применять для новых паролей, т.к. используемое при этом
SHA-1 хэширование без соли уязвимо к взлому при помощи
<link url="http://en.wikipedia.org/wiki/Rainbow_attack">радужных таблиц</link>.
</note>
</listitem>

</list>
</para>

</directive>

</section>

</module>