Перейти к содержанию

auth-totp: Аутентификация на основе временного одноразового пароля (TOTP) для NGINX

Установка на Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-auth-totp, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-auth-totp
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия            | Компонент   | Архитектуры      |
|-------------|-------------------|-------------|------------------|
| debian      | bookworm          | main        | amd64, arm64     |
| debian      | bookworm-mainline | main        | amd64, arm64     |
| debian      | trixie            | main        | amd64, arm64     |
| debian      | trixie-mainline   | main        | amd64, arm64     |
| ubuntu      | focal             | main        | amd64, arm64     |
| ubuntu      | focal-mainline    | main        | amd64, arm64     |
| ubuntu      | jammy             | main        | amd64, arm64     |
| ubuntu      | jammy-mainline    | main        | amd64, arm64     |
| ubuntu      | noble             | main        | amd64, arm64     |
| ubuntu      | noble-mainline    | main        | amd64, arm64     |

Аутентификация на основе временного одноразового пароля (TOTP) для Nginx

Алгоритм временного одноразового пароля (TOTP) предоставляет безопасный механизм для получения значений одноразового пароля с коротким сроком действия, что желательно для повышения безопасности. Этот алгоритм может использоваться в широком круге сетевых приложений, начиная от удалённого доступа к виртуальным частным сетям (VPN), входа в Wi-Fi сеть и заканчивая веб-приложениями, ориентированными на транзакции.

Модуль nginx-http-auth-totp обеспечивает аутентификацию TOTP для сервера Nginx.

Особенности

  • HTTP базовая аутентификация с использованием временного одноразового пароля (TOTP)
  • Отслеживание аутентифицированных клиентов на основе куки за пределами окна действительности TOTP
  • Настраиваемые секрет, временная ссылка, временной шаг и длина обрезки для генерации TOTP
  • Настраиваемая временная разница для валидации TOTP

Пакеты

Для пользователей, предпочитающих предсобранные и оптимизированные пакеты, модуль nginx-http-auth-totp можно установить из репозитория GetPageSpeed:

dnf -y install https://extras.getpagespeed.com/release-latest.rpm 
dnf -y install nginx-module-auth-totp

Конфигурация

server {
    listen 80;

    location /protected {
        auth_totp_realm "Protected";
        auth_totp_file /etc/nginx/totp.conf;
        auth_totp_length 8;
        auth_totp_skew 1;
        auth_totp_step 1m;
        auth_totp_cookie "totp-session";
        auth_totp_expiry 1d;
    }
}

Включите модуль, добавив следующее в верхнюю часть /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_totp_module.so;

Директивы

  • синтаксис: auth_totp_cookie <name>
  • значение по умолчанию: totp
  • контекст: http, server, location, limit_except

Указывает имя HTTP куки, используемого для отслеживания аутентифицированных клиентов.

Когда срок действия временного одноразового пароля (TOTP), используемого для аутентификации, истекает (по замыслу), устанавливается HTTP куки после успешной аутентификации, чтобы сохранить аутентификацию клиента за пределами окна действительности TOTP. Эта конфигурационная директива указывает имя, используемое при установке этого куки, тогда как срок действия этого куки может быть установлен с помощью директивы auth_totp_expiry.

auth_totp_expiry

  • синтаксис: auth_totp_expiry <interval>
  • значение по умолчанию: 0s
  • контекст: http, server, location, limit_except

Указывает время истечения для HTTP куки, используемого для отслеживания аутентифицированных клиентов.

Если это значение истечения не указано (или установлено в ноль), HTTP куки, используемое для отслеживания аутентифицированных клиентов, будет установлено как сессионное куки, которое будет удалено, когда закончится текущая HTTP сессия клиента. Важно отметить, что браузер определяет, когда заканчивается "текущая сессия", и некоторые браузеры используют восстановление сессии при перезагрузке, что может привести к тому, что сессионные куки будут существовать бесконечно.

auth_totp_file

  • синтаксис: auth_totp_file <filename>
  • значение по умолчанию: -
  • контекст: http, server, location, limit_except

Указывает файл, содержащий имена пользователей и общие секреты для аутентификации на основе временных одноразовых паролей (TOTP).

Этот конфигурационный файл имеет следующий формат:

# комментарий
user1:secret1
user2:secret2
user3:secret3

auth_totp_length

  • синтаксис: auth_totp_length <number>
  • значение по умолчанию: 6
  • контекст: http, server, location, limit_except

Указывает длину обрезки кода временного одноразового пароля (TOTP). Эта длина обрезки может быть от 1 до 8 цифр включительно.

Если предоставленный TOTP имеет другую длину, чем это значение, запрос аутентификации не будет успешным.

auth_totp_realm

  • синтаксис: auth_totp_realm <string>|off
  • значение по умолчанию: off
  • контекст: http, server, location, limit_except

Включает проверку имени пользователя и временного одноразового пароля (TOTP) с использованием протокола "HTTP Basic Authentication". Указанный параметр используется в качестве realm для этой аутентификации. Значение этого параметра может содержать переменные. Специальное значение off отменяет применение любой директивы auth_totp_realm, унаследованной от более высокого уровня конфигурации.

auth_totp_reuse

  • синтаксис: auth_totp_reuse <on>|<off>
  • значение по умолчанию: off
  • контекст: http, server, location, limit_except

Включает повторное использование временного одноразового пароля (TOTP) в рамках окна действительности. Хотя это и является нестандартным поведением согласно RFC 6238, это предоставляет удобный способ обеспечить минимальное окно действительности для сгенерированных кодов TOTP, даже если TOTP уже был представлен системе валидации.

auth_totp_skew

  • синтаксис: auth_totp_skew <number>
  • значение по умолчанию: 1
  • контекст: http, server, location, limit_except

Указывает количество временных шагов между системами выдачи и валидации TOTP.

Из-за сетевой задержки разрыв между временем генерации OTP и временем его получения в системе валидации может быть значительным. Действительно, может случиться так, что время получения на системе валидации и время генерации OTP на системе выдачи могут не попадать в одно и то же окно временных шагов. Соответственно, система валидации должна обычно установить политику относительно приемлемого окна передачи OTP для валидации. В связи с этим система валидации должна сравнивать OTP не только с временным штампом получения, но и с прошедшими временными штампами, находящимися в пределах задержки передачи.

Важно отметить, что большие приемлемые окна задержки представляют собой большее окно для атак, и необходимо найти баланс между безопасностью и удобством использования OTP.

auth_totp_start

  • синтаксис: auth_totp_start <time>
  • значение по умолчанию: 0
  • контекст: http, server, location, limit_except

Указывает UNIX время, с которого начинать отсчет временных шагов в рамках операций алгоритма временного одноразового пароля (TOTP).

Значение по умолчанию - 0, UNIX эпоха на 1970/01/01.

auth_totp_step

  • синтаксис: auth_totp_step <interval>
  • значение по умолчанию: 30s
  • контекст: http, server, location, limit_except

Указывает временной шаг в рамках операций алгоритма временного одноразового пароля (TOTP).

Ссылки