auth-totp: 基于时间的一次性密码（TOTP）认证模块 for 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.1.0，于 2024 年 12 月 18 日发布。

基于时间的一次性密码（TOTP）认证 for Nginx

基于时间的一次性密码（TOTP）算法提供了一种安全的机制，用于生成短期有效的一次性密码值，这对于增强安全性是非常重要的。该算法可用于广泛的网络应用，从远程虚拟专用网络（VPN）访问、Wi-Fi 网络登录到面向交易的 Web 应用程序。

nginx-http-auth-totp 模块为 Nginx 服务器提供 TOTP 认证。

特性

使用基于时间的一次性密码（TOTP）的 HTTP 基本认证
基于 Cookie 的认证客户端跟踪，超出 TOTP 有效窗口
可配置的密钥、时间参考、时间步长和 TOTP 生成的截断长度
可配置的 TOTP 验证时间偏差

包

对于喜欢预构建和优化包的用户，可以从 GetPageSpeed 仓库安装 nginx-http-auth-totp 模块：

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

语法: 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

启用使用“HTTP 基本认证”协议验证用户名和基于时间的一次性密码（TOTP）。指定的参数用作此认证的 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，还要与在传输延迟内的过去时间戳进行比较。

重要的是要注意，较大的可接受延迟窗口代表了更大的攻击窗口，必须在 OTP 的安全性和可用性之间取得平衡。

auth_totp_start

语法: auth_totp_start <time>
默认: 0
上下文: http, server, location, limit_except

指定从 UNIX 时间开始计算时间步长，作为基于时间的一次性密码（TOTP）算法操作的一部分。

默认值为 0，即 1970/01/01 的 UNIX 纪元。

auth_totp_step

语法: auth_totp_step <interval>
默认: 30s
上下文: http, server, location, limit_except

指定作为基于时间的一次性密码（TOTP）算法操作的一部分的时间步长。

参考

GitHub

您可以在 nginx-module-auth-totp 的 GitHub 仓库中找到此模块的其他配置提示和文档。