Skip to content

auth-pam: PAM authentication dynamic module for NGINX


CentOS/RHEL 6, 7, 8 or Amazon Linux 2

yum -y install
yum -y install nginx-module-auth-pam

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/;

This document describes nginx-module-auth-pam v1.5.2 released on Jun 23 2020.

Nginx module to use PAM for simple http authentication


The module only has two directives:

  • auth_pam: This is the http authentication realm. If given the value off the module is disabled (needed when we want to override the value set on a lower-level directive).

  • auth_pam_service_name: this is the PAM service name and by default it is set to nginx.


To protect everything under /secure you will add the following to the nginx.conf file:

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

Note that the module runs as the web server user, so the PAM modules used must be able to authenticate the users without being root; that means that if you want to use the module to autenticate users you need to let the web server user to read the /etc/shadow file if that does not scare you (on Debian like systems you can add the www-data user to the shadow group).

As an example, to authenticate users against an LDAP server (using the module) you will use an /etc/pam.d/nginx like the following:

auth    required     /lib/security/
account required     /lib/security/

If you also want to limit the users from LDAP that can authenticate you can use the module; to limit who can access resources under /restricted add the following to the nginx.conf file:

location /restricted {
    auth_pam              "Restricted Zone";
    auth_pam_service_name "nginx_restricted";

Use the following /etc/pam.d/nginx_restricted file:

auth    required     /lib/security/ onerr=fail item=user \
                     sense=allow file=/etc/nginx/restricted_users
auth    required     /lib/security/
account required     /lib/security/

And add the users allowed to authenticate to the /etc/nginx/restricted_users (remember that the web server user has to be able to read this file).

PAM Environment

If you want use the plugin for request based authentication the module can add to the PAM environment the HOST and REQUEST variables if you set the auth_pam_set_pam_env flag::

location /pam_exec_protected {
  auth_pam              "Exec Zone";
  auth_pam_service_name "nginx_exec";
  auth_pam_set_pam_env  on;

With this configuration if you access an URL like:


the PAM environment will include the following variables:

REQUEST=GET /pam_exec_protected/page?foo=yes&bar=too HTTP/1.1

You may use this information for request based authentication. You need a recent pam release (>= version 1.0.90) to expose environment variables to pam_exec.


You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-auth-pam.