auth-pam: NGINX 的 PAM 认证动态模块
需要 GetPageSpeed NGINX Extras 订阅的专业计划（或更高版本）。
安装
您可以在任何基于 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
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-auth-pam
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-pam
通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用该模块：
load_module modules/ngx_http_auth_pam_module.so;
本文档描述的是 nginx-module-auth-pam v1.6.1，于 2026 年 2 月 15 日发布。
企业级 PAM 认证用于 NGINX
概述
此模块通过 PAM（可插拔认证模块）为 NGINX 提供 HTTP 基本认证。
- 完整的自下而上的实现（不是分支）
- 与遗留配置兼容
- 加强的安全性，在生产环境中经过考验
主要特性
- 通过 PAM 实现 HTTP 基本认证
- 领域中的变量扩展（条件认证）
- PAM 环境导出（HOST, REQUEST）
- 在共享内存中缓存认证结果（提高 LDAP/AD 性能）
- 通过线程池进行异步认证（非阻塞工作进程）
- 支持动态模块
配置
| 指令 | 默认值 | 描述 |
|---|---|---|
auth_pam |
- | HTTP 基本认证的领域名称。支持变量。设置为 off 以禁用。 |
auth_pam_service_name |
nginx |
PAM 服务名称（与 /etc/pam.d/<name> 匹配） |
auth_pam_set_pam_env |
off |
将 HOST 和 REQUEST 导出到 PAM 环境 |
auth_pam_cache_zone |
- | 定义共享内存区域：zone=name:size（仅限 http 上下文） |
auth_pam_cache |
- | 启用认证缓存：zone=name time=60s |
auth_pam_thread_pool |
default |
用于异步认证的线程池（需要 --with-threads）。设置为 off 以启用同步模式。 |
示例
基本用法
使用 PAM 认证保护一个位置：
location /secure {
auth_pam "安全区域";
auth_pam_service_name "nginx";
}
创建 PAM 服务文件 /etc/pam.d/nginx：
auth required pam_unix.so
account required pam_unix.so
LDAP 认证
使用 PAM LDAP 模块进行基于目录的认证：
location /ldap-protected {
auth_pam "LDAP 区域";
auth_pam_service_name "nginx_ldap";
}
PAM 服务文件 /etc/pam.d/nginx_ldap：
auth required pam_ldap.so
account required pam_ldap.so
认证缓存
缓存成功的认证以减少 PAM 后端的负载（对 LDAP/AD 特别有用）：
http {
auth_pam_cache_zone zone=pam_cache:1m;
server {
location /cached-auth {
auth_pam "缓存区域";
auth_pam_service_name "nginx_ldap";
auth_pam_cache zone=pam_cache time=60s;
}
}
}
注意： - 仅缓存成功的认证（失败的尝试始终会触及 PAM） - 密码在缓存键中以 SHA1 哈希存储，绝不以明文存储 - 服务名称包含在缓存键中，以防止跨服务冲突 - 推荐的 TTL：60s（默认），根据安全要求进行调整
异步认证（线程池）
当 NGINX 使用 --with-threads 编译时，PAM 认证会自动卸载到线程池。这防止了慢速 PAM 后端（LDAP/AD）阻塞工作进程。
## 默认行为 - 自动使用 NGINX 的 "default" 线程池
location /protected {
auth_pam "受限区域";
auth_pam_service_name "nginx_ldap";
}
## 为高流量认证使用自定义线程池
thread_pool pam_pool threads=4 max_queue=256;
http {
server {
location /high-volume {
auth_pam "高流量区域";
auth_pam_service_name "nginx_ldap";
auth_pam_thread_pool pam_pool;
}
}
}
## 强制同步模式（禁用异步）
location /sync-auth {
auth_pam "同步区域";
auth_pam_service_name "nginx";
auth_pam_thread_pool off;
}
注意：
- 需要使用 --with-threads 编译的 NGINX
- 在提交到线程池之前检查缓存（缓存命中的快速路径）
- 如果线程池队列已满，则返回 503
条件认证
跳过证书认证的客户端的 PAM：
map $ssl_client_verify $pam_realm {
SUCCESS "off";
default "受限区域";
}
server {
listen 443 ssl;
ssl_client_certificate /etc/nginx/ca.crt;
ssl_verify_client optional;
location /api {
auth_pam $pam_realm;
auth_pam_service_name "nginx";
}
}
对内部网络禁用认证：
geo $pam_realm {
default "受限";
10.0.0.0/8 "off";
}
location /internal {
auth_pam $pam_realm;
auth_pam_service_name "nginx";
}
使用 pam_exec 的 PAM 环境
将请求细节导出到 PAM 以进行自定义认证脚本：
location /custom-auth {
auth_pam "自定义区域";
auth_pam_service_name "nginx_exec";
auth_pam_set_pam_env on;
}
启用时，PAM 环境包括：
HOST- 请求主机头（例如，localhost:8000）REQUEST- 完整请求行（例如，GET /path?query HTTP/1.1）
PAM 服务文件 /etc/pam.d/nginx_exec：
auth required pam_exec.so /path/to/auth-script.sh
account required pam_permit.so
使用 $pam_user 变量
成功 PAM 认证后，$pam_user 变量包含经过认证的用户名：
location /api {
auth_pam "API 访问";
auth_pam_service_name "nginx";
# 为后端添加用户名头
proxy_set_header X-Authenticated-User $pam_user;
proxy_pass http://backend;
}
## 带用户名的自定义访问日志
log_format auth '$remote_addr - $pam_user [$time_local] "$request"';
access_log /var/log/nginx/access.log auth;
注意：
- 当 auth_pam off 或认证失败时为空
- 适用于同步、异步（线程池）和缓存认证