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

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-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.8.0，于 2026 年 2 月 14 日发布。

企业级 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              "Secure Zone";
    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 Zone";
    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              "Cached Zone";
            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              "Restricted";
    auth_pam_service_name "nginx_ldap";
}

# 为高流量认证使用自定义线程池
thread_pool pam_pool threads=4 max_queue=256;

http {
    server {
        location /high-volume {
            auth_pam              "High Volume Zone";
            auth_pam_service_name "nginx_ldap";
            auth_pam_thread_pool  pam_pool;
        }
    }
}

# 强制同步模式（禁用异步）
location /sync-auth {
    auth_pam              "Sync Zone";
    auth_pam_service_name "nginx";
    auth_pam_thread_pool  off;
}

注意： - 需要使用 --with-threads 编译的 NGINX - 在提交到线程池之前会检查缓存（缓存命中的快速路径） - 如果线程池队列已满，则返回 503

条件认证

跳过证书认证的客户端的 PAM 认证：

map $ssl_client_verify $pam_realm {
    SUCCESS "off";
    default "Restricted Area";
}

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     "Restricted";
    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              "Custom Zone";
    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