使用 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 项目中快速构建轻量级的访问控制体系。