Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



31 Commits

Repository files navigation


Nginx module to use PAM for simple http authentication


When compiling from source build as usual adding the --add-module option:

./configure --add-module=$PATH_TO_MODULE

or if you want to build the module as dynamic use the --add-dynamic-module option.

If you are using a Debian GNU/Linux distribution install the nginx-full package; the module has been included in the debian package since version 1.1.6-1, so it is available on all stable distributions since the wheezy release.


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.


Nginx module to use PAM for simple http authentication







No packages published