ngx_http_auth_pam_module: A C repository from r10r

Nginx module to use PAM for simple http authentication
======================================================

:Date: $Date: 2010-11-15 12:35:32 +0100 (dl 15 de nov de 2010) $
:Revision: $Rev: 4488 $

Compilation
-----------

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

  ./configure --add-module=$PATH_TO_MODULE

If you are using a Debian GNU/Linux distribution is easy to build a modified
package that includes this module::

  # Get the source
  apt-get source nginx
  # Copy the module
  NGINX_DEBIAN=$(ls -d nginx-*/debian)
  mkdir $NGINX_DEBIAN/ngx_http_auth_pam_module
  cp config  $NGINX_DEBIAN/ngx_http_auth_pam_module/
  cp ngx_http_auth_pam_module.c $NGINX_DEBIAN/ngx_http_auth_pam_module/
  cd $NGINX_DEBIAN; cd ..;
  # Add the argument ``--add-module=./debian/ngx_http_auth_pam_module`` to the
  # ./configure call on the debian/rules file
  sed -i -e '/.\/configure .*\\$/,/[^\\]$/ {
    /^.*[^\\]$/ { 
      s%^\(.*\)$%\t    --add-module=./debian/ngx_http_auth_pam_module \\\n\1%;
    }
  }' debian/rules
  # Add the libpam-dev build dependency
  sed -i -e 's/^Build-Depends: /Build-Depends: libpam-dev, /;' debian/control
  # Update the package version using the dch command from devscripts
  dch -l'+authpam' 'Added ngx_http_auth_pam_module support'
  # Build the package 
  dpkg-buildpackage
  # And install
  sudo dpkg -i ../nginx*deb

Configuration
-------------

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``.

Examples
--------

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 ``pam_unix.so`` 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
``pam_ldap.so`` module) you will use an ``/etc/pam.d/nginx`` like the following::

  auth    required     /lib/security/pam_ldap.so
  account required     /lib/security/pam_ldap.so

If you also want to limit the users from LDAP that can authenticate you can
use the ``pam_listfile.so`` 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/pam_listfile.so onerr=fail item=user \
                       sense=allow file=/etc/nginx/restricted_users
  auth    required     /lib/security/pam_ldap.so
  account required     /lib/security/pam_ldap.so

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
---------------

The plugin set's the following additional environment variables when using ``pam_exec.so``
as pam module for authentication:

	REQUEST=GET /some/url?foo&bar HTTP/1.1
	HOST=localhost:8000

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 (Ubuntu 8.04 has a too old pam version here!).


.. ......
.. SVN Id: $Id: README 4488 2010-11-15 11:35:32Z sto $
r10r/ngx_http_auth_pam_module
