使用 NGINX 实现 HTTP Basic 认证ngx_http_auth_basic_module 模块
一、前言
在 Web 应用中，对部分资源进行访问控制是十分常见的需求。除了基于 IP 限制、JWT 验证、子请求校验等方式外，最经典也最简单的一种方式便是 HTTP Basic Authentication。NGINX 提供的 ngx_http_auth_basic_module 模块支持基于用户名和密码的基本认证，搭配密码文件使用即可快速生效，适合临时保护内网站点、管理后台或演示环境。
本文将介绍该模块的基本原理、配置方式、安全注意事项，以及配套使用 htpasswd 工具生成密码文件的实践步骤。
二、模块简介
- 模块名称：
ngx_http_auth_basic_module - 主要用途：限制资源访问，要求客户端输入用户名和密码进行认证
- 认证方式：基于 HTTP 标准的
Basic认证协议 - 依赖文件：密码文件
htpasswd，包含加密后的用户名密码对
三、基本配置
示例：
location /admin/ {auth_basic "Admin Area"; # 认证提示字符串（realm）auth_basic_user_file /etc/nginx/.htpasswd; # 密码文件路径
}
用户访问 /admin/ 时，将收到 401 提示，浏览器弹出认证对话框，需输入有效的用户名和密码才能访问。
四、指令详解
1. auth_basic
auth_basic "提示字符串" | off;
- 启用 Basic 认证，并设置提示信息（如“Protected”）
- 使用
off可取消继承自上级的认证设置
2. auth_basic_user_file
auth_basic_user_file /路径/文件名;
- 指定密码文件路径
- 支持变量（如
$document_root) - 文件格式支持多种加密方案，详见下节
五、密码文件格式与生成
支持的密码格式包括：
- crypt() 加密：传统 Unix 加密方式，兼容性强
- MD5 (apr1)：Apache 的变体，加密强度较高
- SSHA / SHA：OpenLDAP/Dovecot 使用，但不推荐使用
SHA（无盐，易被彩虹表攻击）
推荐方式：使用 Apache 提供的 htpasswd 工具生成
安装：
Ubuntu / Debian：
sudo apt install apache2-utils
Mac（通过 Homebrew）：
brew install httpd
创建密码文件：
# 创建新文件并添加用户
htpasswd -c /etc/nginx/.htpasswd admin# 添加其他用户（无需 -c）
htpasswd /etc/nginx/.htpasswd user2
执行后输入密码，文件内容示例：
admin:$apr1$Jz2Wx...$gDzVpzESXk3evm7aTnt1C1
user2:$apr1$T5bsw...$EOczxO2wqlfy5Iod5kZqf/
注：该文件权限建议设置为 640，并限制仅 NGINX 用户可读。
六、进阶用法
1. 结合 IP 限制：使用 satisfy 指令
location /internal/ {satisfy any;allow 192.168.0.0/24;deny all;auth_basic "Restricted";auth_basic_user_file /etc/nginx/.htpasswd;
}
上述配置表示：来自内网地址即可访问，其他请求必须通过 Basic 认证。
2. 区块级控制：仅保护部分接口或目录
location /docs/private/ {auth_basic "Docs Login";auth_basic_user_file /etc/nginx/docs_passwd;
}
用于保护在线文档、临时演示页等。
七、安全注意事项
- 认证信息为明文传输，强烈建议配合 HTTPS 使用
- 密码文件中不可使用明文密码，需使用加密方式存储
- 不推荐使用
{SHA}，应优先使用apr1或bcrypt（OpenResty 用户可结合 Lua 模块） - 大量用户时，建议使用数据库认证方式或 JWT 替代 Basic Auth
八、总结
NGINX 的 ngx_http_auth_basic_module 提供了简单而高效的认证机制，尤其适用于中小型项目的访问控制、临时资源保护等场景。通过几行配置和一个 htpasswd 文件即可快速上线认证机制。结合 satisfy 实现复合控制，还可支持灵活的访问策略。
尽管 Basic Auth 存在加密弱点，但在内网或搭配 HTTPS 使用场景下，依旧是一个便捷的工具。掌握该模块，有助于你在各类 Web 项目中快速构建轻量级的访问控制体系。