Базовая HTTP-авторизация в Nginx

Логотип Nginx.

Быстрые ссылки

Как работает HTTP-авторизация?
Генерация файла паролей
Включение базовой HTTP-авторизации
Авторизация при проксировании

Как работает HTTP-авторизация?

В базовой HTTP-авторизации отдельные маршруты сервера защищены и требуют имени пользователя и пароля для доступа. Когда клиент запрашивает защищённый ресурс, сервер отвечает с заголовком

WWW-Authenticate

и статусом

401 Unauthorized

Клиент затем отправляет заголовок

Authorization

со значением, содержащим закодированные учётные данные. Сервер сравнивает присланные данные с хранящимися значениями (например, в htpasswd-файле). При совпадении доступ разрешается.

Важно: базовая авторизация передаёт учётные данные в кодировке Base64, а не в зашифрованном виде. Поэтому всегда используйте HTTPS/TLS, чтобы предотвратить перехват паролей в сети.

Короткая дефиниция: HTTPS — протокол передачи, шифрующий данные между клиентом и сервером.

Генерация файла паролей

Для создания файла паролей используйте утилиту htpasswd из пакета apache2-utils. Nginx использует тот же формат паролей, что и Apache.

Установка (Debian/Ubuntu):

sudo apt-get install apache2-utils

Создание нового файла паролей и добавление пользователя admin:

sudo htpasswd -c /etc/nginx/.htpasswd admin

Подсказки:

Флаг -c создаёт новый файл. Чтобы добавить пользователей в существующий файл, не используйте -c.
htpasswd по умолчанию использует криптографические хеши (bcrypt/MD5/sha), в зависимости от реализации. Это лучше, чем хранить пароли в открытом виде.
Защитите файл .htpasswd правами доступа на уровне ОС: например, chmod 640 и владелец root.

Включение базовой HTTP-авторизации

Добавьте директивы auth_basic и auth_basic_user_file в нужный location в конфигурации Nginx (обычно /etc/nginx/nginx.conf или отдельные файлы в /etc/nginx/sites-available):

location /admin {
    try_files $uri $uri/ =404;

    auth_basic "Restricted Content";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Пояснения:

auth_basic задаёт текст realm, который увидит пользователь при запросе учётных данных. Подставляйте понятный для ваших пользователей текст.
auth_basic_user_file указывает путь к файлу паролей.

Примените изменения перезапуском Nginx:

sudo service nginx restart

Проверьте в браузере: при обращении к защищённому маршруту должна появиться форма ввода логина и пароля.

Важно: не разрабатывайте основанную на базовой авторизации публичную API-защиту без HTTPS.

Авторизация при проксировании

Частая задача — защитить внешний ресурс через Nginx как обратный прокси. Простая конфигурация с auth_basic выглядит так:

location / {
    # turn on auth for this location
    auth_basic "Restricted Content";
    auth_basic_user_file /etc/nginx/.htpasswd;

    # normal proxy configuration
    proxy_http_version 1.1;
    proxy_pass_request_headers on;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Accept-Encoding "";
    proxy_pass https://;
    proxy_redirect default;
}

Такая конфигурация не пропускает запрос в бэкенд, пока клиент не авторизуется в Nginx.

Если же аутентификацию должен выполнять сам бэкенд (например, он проверяет учётные записи в базе данных или использует сложную логику), то необходимо пробрасывать заголовок Authorization к бэкенду. Для этого используется модуль headers-more (more_set_input_headers и more_set_headers):

location / {
    proxy_http_version 1.1;
    proxy_pass_request_headers on;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Accept-Encoding "";
    proxy_pass https://;
    proxy_redirect default;

    more_set_input_headers 'Authorization: $http_authorization';
    more_set_headers -s 401 'WWW-Authenticate: Basic realm="your_server.com"';
}

Пояснения:

more_set_input_headers передаёт клиентский заголовок Authorization на бэкенд.
more_set_headers корректно формирует заголовок WWW-Authenticate при ответе 401, не перезаписывая realm.
Модуль headers-more нужно подключить в сборке Nginx или установить как динамический модуль.

Когда базовая авторизация не подходит

API-публичные интерфейсы. Базовая авторизация передаёт учётные данные и не подходит для RESTful API без дополнительных мер (лучше использовать токены, OAuth2, API-ключи).
Масштабируемые приложения с централизованной аутентификацией. Для единой авторизации используйте OAuth2, OpenID Connect, LDAP, SSO.
Сложная авторизация (роли/права). Базовая авторизация проста и не включает уровней прав; понадобится дополнительная логика на бэкенде.

Альтернативные подходы

Токены (Bearer tokens, JWT) — подходят для API и мобильных клиентов. Они позволяют без повторной отправки логина/пароля управлять сессиями.
Client TLS certificates — сильная защита для машинных клиентов; требует PKI-инфраструктуры.
Central auth service (OAuth2 / OpenID Connect) — для единой точки входа и SSO.
LDAP/Active Directory — для корпоративной аутентификации и управления пользователями.

Безопасность и жёсткие настройки

Всегда включайте HTTPS/TLS. Сертификаты можно получить бесплатно через Let’s Encrypt.
Разделяйте файлы паролей для разных зон и давайте минимальные права на чтение.
Логи: не логируйте заголовки Authorization. Внимательно настройте access_log и error_log.
Ограничение попыток входа: используйте rate limiting (limit_req), fail2ban или внешние WAF.
Хеширование паролей: используйте современные алгоритмы; htpasswd обычно применяет безопасные хеши, но контролируйте реализацию системы.
Обновляйте Nginx и модули, чтобы получать исправления безопасности.

Примеры отказа и отладка

Браузер не запрашивает логин: проверьте, что директивы auth_basic находятся внутри корректного location/server блока и нет директив, отключающих их.
Ошибка 500 при перезапуске Nginx: проверьте синтаксис конфигурации nginx -t.
Заголовок Authorization не передаётся: убедитесь, что proxy_pass_request_headers on и используете more_set_input_headers для проброса.
Realm не виден клиенту: use more_set_headers для корректной установки WWW-Authenticate на 401.

Критерии приёмки

Доступ к защищённому маршруту требует логина/пароля.
Сервер отвечает 401, если учётные данные отсутствуют или неверны.
При корректных данных доступ разрешён и проксирование работает.
Заголовок Authorization не попадает в лог-файлы.
TLS активирован для соответствующих виртуальных хостов.

Тестовые сценарии

Позитивный: curl с верными учётными данными возвращает 200/ожидаемый ресурс.
Негативный: curl без учётных данных получает 401 с заголовком WWW-Authenticate.
Проксирование: с проброшенным Authorization бэкенд получает заголовок и выполняет свою аутентификацию.

Факты и полезные значения

Типичный путь файла: /etc/nginx/.htpasswd
Команда для создания: htpasswd -c /etc/nginx/.htpasswd username
Порты: HTTP 80, HTTPS 443
Модуль для проброса заголовков: headers-more (more_set_input_headers, more_set_headers)

Памятка для ролей

DevOps: создать и защитить файл .htpasswd, настроить TLS, протестировать конфигурацию.
Backend-разработчик: если аутентификация на бэкенде, обеспечить обработку Authorization и корректные ответы 401 с WWW-Authenticate.
Системный администратор: следить за правами файлов, обновлениями и логированием.

Ментальные модели и решение “что выбрать”

Если нужен быстрый способ закрыть административный интерфейс — используйте auth_basic + htpasswd.
Если нужна интеграция с корпоративной системой — выберите LDAP/SSO/OAuth.
Для API — отдавайте предпочтение токенам/JWT и специализированным механизмам управления сессиями.

Пример карты решений (Mermaid)

flowchart TD
    A[Нужно ли быстро закрыть интерфейс?] -->|Да| B[Использовать auth_basic + htpasswd]
    A -->|Нет| C[Нужна централизованная аутентификация]
    C --> D{Тип клиентов}
    D -->|Браузерные пользователи| E[SSO / OAuth2]
    D -->|API клиенты| F[Bearer tokens / JWT]
    D -->|Машины/серверы| G[Client TLS certificates]

Приватность и соответствие правилам

Храните учётные записи так, чтобы минимизировать доступ к паролям. При обработке персональных данных учитывайте требования локального законодательства и корпоративные политики. Базовая авторизация сама по себе не передаёт дополнительной персональной информации, но если логируются идентификаторы пользователей — проверьте соответствие правилам хранения логов.

Краткое резюме

Базовая HTTP-авторизация в Nginx — быстрый и простой способ защитить внутренние или административные маршруты. Она не заменяет более продвинутые решения для API и корпоративной аутентификации, но хороша для многих сценариев при условии использования HTTPS и дополнительных мер безопасности.

Важное: перед внедрением убедитесь, что все ключевые моменты (TLS, права доступа к файлам, логирование и rate limiting) настроены корректно.