README.md
1# ngx_http_auth_pam_module
2
3## Nginx module to use PAM for simple http authentication
4
5### Compilation
6
7When compiling from source build as usual adding the ``--add-module`` option:
8
9 ./configure --add-module=$PATH_TO_MODULE
10
11or if you want to build the module as dynamic use the ``--add-dynamic-module``
12option.
13
14If you are using a Debian GNU/Linux distribution install the ``nginx-full``
15package; the module has been included in the debian package since version
16``1.1.6-1``, so it is available on all stable distributions since the *wheezy*
17release.
18
19### Configuration
20
21The module only has two directives:
22
23- ``auth_pam``: This is the http authentication realm. If given the value
24 ``off`` the module is disabled (needed when we want to override the value
25 set on a lower-level directive).
26
27- ``auth_pam_service_name``: this is the PAM service name and by default it is
28 set to ``nginx``.
29
30### Examples
31
32To protect everything under ``/secure`` you will add the following to the
33``nginx.conf`` file:
34
35 location /secure {
36 auth_pam "Secure Zone";
37 auth_pam_service_name "nginx";
38 }
39
40Note that the module runs as the web server user, so the PAM modules used must
41be able to authenticate the users without being root; that means that if you
42want to use the ``pam_unix.so`` module to autenticate users you need to let the
43web server user to read the ``/etc/shadow`` file if that does not scare you (on
44Debian like systems you can add the ``www-data`` user to the ``shadow`` group).
45
46As an example, to authenticate users against an LDAP server (using the
47``pam_ldap.so`` module) you will use an ``/etc/pam.d/nginx`` like the
48following:
49
50 auth required /lib/security/pam_ldap.so
51 account required /lib/security/pam_ldap.so
52
53If you also want to limit the users from LDAP that can authenticate you can
54use the ``pam_listfile.so`` module; to limit who can access resources under
55``/restricted`` add the following to the ``nginx.conf`` file:
56
57 location /restricted {
58 auth_pam "Restricted Zone";
59 auth_pam_service_name "nginx_restricted";
60 }
61
62Use the following ``/etc/pam.d/nginx_restricted`` file:
63
64 auth required /lib/security/pam_listfile.so onerr=fail item=user \
65 sense=allow file=/etc/nginx/restricted_users
66 auth required /lib/security/pam_ldap.so
67 account required /lib/security/pam_ldap.so
68
69And add the users allowed to authenticate to the ``/etc/nginx/restricted_users``
70(remember that the web server user has to be able to read this file).
71
72### PAM Environment
73
74If you want use the ``pam_exec.so`` plugin for request based authentication the
75module can add to the PAM environment the ``HOST`` and ``REQUEST`` variables if
76you set the ``auth_pam_set_pam_env`` flag::
77
78 location /pam_exec_protected {
79 auth_pam "Exec Zone";
80 auth_pam_service_name "nginx_exec";
81 auth_pam_set_pam_env on;
82 }
83
84With this configuration if you access an URL like:
85
86 http://localhost:8000/pam_exec_protected/page?foo=yes&bar=too
87
88the PAM environment will include the following variables:
89
90 HOST=localhost:8000
91 REQUEST=GET /pam_exec_protected/page?foo=yes&bar=too HTTP/1.1
92
93You may use this information for request based authentication.
94You need a recent pam release (>= version 1.0.90) to expose environment
95variables to pam_exec.
96