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

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

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

  • RedHat Enterprise Linux 7, 8, 9 и 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 и Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-auth-totp

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-auth-totp

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

load_module modules/ngx_http_auth_totp_module.so;

Этот документ описывает nginx-module-auth-totp v1.1.0, выпущенный 18 декабря 2024 года.

Аутентификация на основе временного одноразового пароля (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 не только с временной меткой получения, но и с прошедшими временными метками, которые находятся в пределах задержки передачи.

Важно отметить, что более крупные приемлемые окна задержки представляют собой более широкое окно для атак, и необходимо найти баланс между безопасностью и удобством использования 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).

Ссылки

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-auth-totp.