auth-pam: Módulo dinâmico de autenticação PAM para NGINX

Requer o plano Pro (ou superior) da assinatura GetPageSpeed NGINX Extras.

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

RedHat Enterprise Linux 7, 8, 9 e 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 e Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e 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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_pam_module.so;

Este documento descreve nginx-module-auth-pam v1.8.0 lançado em 14 de fevereiro de 2026.

Autenticação PAM de nível empresarial para NGINX

Visão Geral

Este módulo fornece autenticação HTTP Basic via PAM (Pluggable Authentication Modules) para NGINX.

Implementação completa do zero (não é um fork)
Compatível com configurações legadas
Segurança reforçada, testada em produção

Principais Recursos

HTTP Basic Auth via PAM
Expansão de variáveis no realm (autenticação condicional)
Exportação de ambiente PAM (HOST, REQUEST)
Cache de resultados de autenticação na memória compartilhada (para desempenho LDAP/AD)
Autenticação assíncrona via pool de threads (trabalhadores não bloqueantes)
Suporte a módulos dinâmicos

Configuração

Diretiva	Padrão	Descrição
`auth_pam`	-	Nome do realm para autenticação HTTP Basic. Suporta variáveis. Defina como `off` para desativar.
`auth_pam_service_name`	`nginx`	Nome do serviço PAM (corresponde a `/etc/pam.d/<name>`)
`auth_pam_set_pam_env`	`off`	Exportar HOST e REQUEST para o ambiente PAM
`auth_pam_cache_zone`	-	Definir zona de memória compartilhada: `zone=name:size` (apenas contexto http)
`auth_pam_cache`	-	Habilitar cache de autenticação: `zone=name time=60s`
`auth_pam_thread_pool`	`default`	Pool de threads para autenticação assíncrona (requer `--with-threads`). Defina como `off` para modo síncrono.

Exemplos

Uso Básico

Proteja uma localização com autenticação PAM:

location /secure {
    auth_pam              "Secure Zone";
    auth_pam_service_name "nginx";
}

Crie o arquivo de serviço PAM /etc/pam.d/nginx:

auth    required pam_unix.so
account required pam_unix.so

Autenticação LDAP

Use o módulo PAM LDAP para autenticação baseada em diretório:

location /ldap-protected {
    auth_pam              "LDAP Zone";
    auth_pam_service_name "nginx_ldap";
}

Arquivo de serviço PAM /etc/pam.d/nginx_ldap:

auth    required pam_ldap.so
account required pam_ldap.so

Cache de Autenticação

Cacheie autenticações bem-sucedidas para reduzir a carga nos backends PAM (especialmente útil para 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;
        }
    }
}

Notas: - Apenas autenticações bem-sucedidas são armazenadas em cache (tentativas falhadas sempre acessam o PAM) - Senhas são hashadas em SHA1 nas chaves de cache, nunca armazenadas em texto simples - O nome do serviço é incluído na chave de cache para evitar colisões entre serviços - TTL recomendado: 60s (padrão), ajuste com base nos requisitos de segurança

Autenticação Assíncrona (Pool de Threads)

Quando o NGINX é compilado com --with-threads, a autenticação PAM é automaticamente transferida para um pool de threads. Isso impede que backends PAM lentos (LDAP/AD) bloqueiem os processos de trabalho.

# Comportamento padrão - usa automaticamente o pool de threads "default" do NGINX
location /protected {
    auth_pam              "Restricted";
    auth_pam_service_name "nginx_ldap";
}

# Use um pool de threads personalizado para autenticação de alto volume
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;
        }
    }
}

# Forçar modo síncrono (desabilitar assíncrono)
location /sync-auth {
    auth_pam              "Sync Zone";
    auth_pam_service_name "nginx";
    auth_pam_thread_pool  off;
}

Notas: - Requer NGINX compilado com --with-threads - O cache é verificado antes de enviar para o pool de threads (caminho rápido para acertos de cache) - Retorna 503 se a fila do pool de threads estiver cheia

Autenticação Condicional

Ignore o PAM para clientes autenticados por certificado:

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";
    }
}

Desative a autenticação para redes internas:

geo $pam_realm {
    default     "Restricted";
    10.0.0.0/8  "off";
}

location /internal {
    auth_pam $pam_realm;
    auth_pam_service_name "nginx";
}

Ambiente PAM com pam_exec

Exporte detalhes da solicitação para o PAM para scripts de autenticação personalizados:

location /custom-auth {
    auth_pam              "Custom Zone";
    auth_pam_service_name "nginx_exec";
    auth_pam_set_pam_env  on;
}

Quando habilitado, o ambiente PAM inclui:

HOST - Cabeçalho do host da solicitação (por exemplo, localhost:8000)
REQUEST - Linha completa da solicitação (por exemplo, GET /path?query HTTP/1.1)

Arquivo de serviço PAM /etc/pam.d/nginx_exec:

auth required pam_exec.so /path/to/auth-script.sh
account required pam_permit.so