auth-pam: Динамический модуль аутентификации PAM для NGINX

Требует подписки Pro плана (или выше) на 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.6.1, выпущенный 15 февраля 2026 года.

Аутентификация PAM корпоративного уровня для NGINX

Обзор

Этот модуль предоставляет HTTP Basic Authentication через PAM (Pluggable Authentication Modules) для NGINX.

Полная реализация с нуля (не форк)
Совместимость с устаревшими конфигурациями
Укрепленная безопасность, проверенная в боевых условиях

Ключевые особенности

HTTP Basic Auth через PAM
Расширение переменных в realm (условная аутентификация)
Экспорт окружения PAM (HOST, REQUEST)
Кэширование результатов аутентификации в общей памяти (для производительности LDAP/AD)
Асинхронная аутентификация через пул потоков (не блокирующие рабочие процессы)
Поддержка динамических модулей

Конфигурация

Директива	По умолчанию	Описание
`auth_pam`	-	Имя realm для HTTP Basic auth. Поддерживает переменные. Установите в `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).

## Поведение по умолчанию - автоматически использует "default" пул потоков NGINX
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;
}

Примечания: - Требуется NGINX, собранный с --with-threads - Кэш проверяется перед отправкой в пул потоков (быстрый путь для попаданий в кэш) - Возвращает 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 с pam_exec

Экспортируйте детали запроса в 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

Использование переменной `$pam_user`

После успешной аутентификации PAM переменная $pam_user содержит имя аутентифицированного пользователя:

location /api {
    auth_pam              "API Access";
    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 или аутентификация не удалась - Работает с синхронной, асинхронной (пул потоков) и кэшированной аутентификацией