auth-digest: 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-digest

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-digest

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用模块：

load_module modules/ngx_http_auth_digest_module.so;

本文档描述了 nginx-module-auth-digest v1.0.0，于 2018 年 3 月 23 日发布。

与其他分支的变化

错误修复 1, 2, 3

为无效登录尝试添加日志消息

描述

ngx_http_auth_digest 模块通过提供对 RFC 2617 摘要认证的支持，补充了 Nginx 内置的基本认证模块。该模块目前是功能性的，但仅由其作者进行了测试和审查。考虑到这是安全代码，一双眼睛几乎肯定不足以保证其 100% 正确。在收到一些错误报告并消除代码中的一些“未知未知数”之前，请将此模块视为“alpha”，并以适当的怀疑态度对待。

已知问题的列表可以在 bugs.txt 文件中找到，也可以在问题跟踪器中找到。如果您有时间和兴趣，请考虑贡献一个补丁。任何修复错误或将实现更改为更符合 Nginx 风格的帮助都将不胜感激。

示例

您可以通过在 Nginx 配置文件的 server 部分中添加以下行来对目录树进行密码保护：

auth_digest_user_file /opt/httpd/conf/passwd.digest; # 由 htdigest 创建的文件
location /private{
  auth_digest 'this is not for you'; # 为此位置块设置领域
}

其他指令控制认证会话的生命周期默认值。以下示例与之前的示例等效，但演示了所有指令：

auth_digest_user_file /opt/httpd/conf/passwd.digest;
auth_digest_shm_size 4m;   # 用于跟踪活动会话的存储空间

location /private {
  auth_digest 'this is not for you';
  auth_digest_timeout 60s; # 允许用户在接收挑战和在浏览器对话框中点击发送之间等待 1 分钟
  auth_digest_expires 10s; # 在成功挑战/响应后，让客户端在生成新挑战之前继续使用相同的 nonce 进行额外请求 10 秒
  auth_digest_replays 20;  # 如果客户端在过期时间限制之前使用相同的 nonce 超过 20 次，也生成新的挑战
}

向某个位置添加摘要认证将影响与该块匹配的任何 URI。要禁用特定子分支的认证，请将 auth_digest 设置为 off：

location / {
  auth_digest 'this is not for you';
  location /pub {
    auth_digest off; # 此子树将无需认证即可访问
  }
}

指令

auth_digest

语法 auth_digest [realm-name | off]

默认值 off

上下文 server, location

描述为服务器或位置块启用或禁用摘要认证。领域名称应与用户文件中使用的领域相对应。该领域中的任何用户在认证后都将能够访问文件。

要在受保护的 URI 层次结构中选择性地禁用认证，请在更具体的位置块中将 auth_digest 设置为“off”（参见示例）。

auth_digest_user_file

语法 auth_digest_user_file /path/to/passwd/file

默认值 unset

上下文 server, location

描述密码文件应为由 apache htdigest 命令（或包含的 htdigest.py 脚本）创建的形式。文件的每一行都是由用户名、领域和结合名称、领域和密码的 md5 哈希组成的以冒号分隔的列表。例如：joi:enfield:ef25e85b34208c246cfd09ab76b01db7

auth_digest_timeout

语法 auth_digest_timeout delay-time

默认值 60s

上下文 server, location

描述当客户端首次请求受保护的页面时，服务器将返回 401 状态代码以及 www-authenticate 头中的挑战。

此时，大多数浏览器将向用户呈现一个对话框，提示他们登录。此指令定义挑战将保持有效的时间。如果用户在提交其姓名和密码之前等待超过此时间，则挑战将被视为“过时”，他们将被提示再次登录。

auth_digest_expires

语法 auth_digest_expires lifetime-in-seconds

默认值 10s

上下文 server, location

描述一旦客户端成功回答了摘要挑战，后续请求将尝试重用原始挑战中的“nonce”值。为了复杂化 MitM 攻击，最好限制缓存 nonce 被接受的次数。此指令设置首次成功认证后的重用期的持续时间。

auth_digest_replays

语法 auth_digest_replays number-of-uses

默认值 20

上下文 server, location

描述 Nonce 重用也应限制为固定数量的请求。请注意，增加此值将导致内存使用量成比例增加，shm_size 可能需要调整以跟上摘要保护位置块中的高流量。

auth_digest_evasion_time

语法 auth_digest_evasion_time time-in-seconds

默认值 300s

上下文 server, location

描述一旦来自客户端地址的失败认证次数达到 auth_digest_maxtries，服务器将忽略来自该客户端地址的认证请求的时间。

auth_digest_maxtries

语法 auth_digest_maxtries number-of-attempts

默认值 5

上下文 server, location

描述来自客户端地址的失败认证尝试次数，在此之后模块将进入规避策略。出于规避目的，仅跟踪网络客户端，并且仅按地址（不包括端口号）进行跟踪。成功认证将清除计数器。

auth_digest_shm_size

语法 auth_digest_shm_size size-in-bytes

默认值 4096k

上下文 server

描述该模块维护一个固定大小的活动摘要会话缓存，以在经过认证的请求之间保存状态。一旦此缓存满了，直到活动会话过期之前，将无法进行进一步的认证。

因此，选择适当的大小有点棘手，因为它取决于在过期相关指令中设置的值。每个存储的挑战占用 48 + ceil(replays/8) 字节，并将在 auth_digest_timeout + auth_digest_expires 秒内存活。使用默认模块设置时，这大约允许每 70 秒进行 82k 的非重放请求。

GitHub

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