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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

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.2.0, выпущенный 4 мая 2026 года.

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

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

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

Особенности

HTTP базовая аутентификация с использованием временного одноразового пароля (TOTP)
Отслеживание аутентифицированных клиентов на основе cookie за пределами временного окна действительности 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_secret "Secret";
        auth_totp_file /etc/nginx/totp.conf;
        auth_totp_length 8;
        auth_totp_reuse off;
        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

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

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

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

auth_totp_expiry

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

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

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

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_secret

синтаксис: auth_totp_secret <string>
по умолчанию: -
контекст: http, server, location, limit_except

Секрет на стороне сервера, используемый при генерации сессионных cookie и затем при валидации сессионных cookie. Если злоумышленник знает этот секрет, он сможет подделать сессионные cookie, которые предоставляют доступ, поэтому крайне важно, чтобы его было трудно угадать.

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.