Installation Notes for pwauth.c
-------------------------------
This program is designed to be used with Apache to authenticate users out
of the password file. To use it for basic authentication, follow the
instructions below. See the FORM_AUTH instructions for notes on using it
with other forms of authentication.
(1) Install mod_auth_external or mod_authnz_external in Apache. This
version of pwauth requires mod_auth_external version 2.1.1 or later.
You can either recompile Apache with the new modules, or install them
as dynamically loaded modules. See the module installation instructions
for detail.
(2) Edit the config.h file in this directory to set the configuration
appropriate for your system. There are lots of comments in the file.
(3) If you are using PAM on Linux, you could be missing the header files
you need to compile the auth_pam.c file. You may need to load some
sort of PAM development module this isn't part of the standard install
to get these headers.
(4) Edit the Makefile in this directory, setting appropriate CC, LIB and
LOCALFLAGS variables.
(5) Do "make" to compile the program.
(6) If you are using PAM, you need to do some work on the configuration
files. Depending on your operating system, you'll either need to
create a /etc/pam.d/pwauth file or edit the /etc/pam.conf file.
If you have a /etc/pam.d directory, you need to create a file named
"pwauth" inside it. To authenticate out of the Unix Shadow file
under Redhat 6.x, the /etc/pam.d/pwauth file should look something like
this:
auth required /lib/security/pam_pwdb.so shadow nullok
auth required /lib/security/pam_nologin.so
account required /lib/security/pam_pwdb.so
Under OS X 10.4.11, something like the following works (possibly the
pam_securityserver line should be removed):
auth required pam_nologin.so
auth sufficient pam_securityserver.so
auth sufficient pam_unix.so
auth required pam_deny.so
account required pam_permit.so
If you have a /etc/pam.conf file instead of a /etc/pam.d directory,
then you need to add appropriate lines to that instead. For
Solaris 2.6, you need to add lines like this to authenticate out
of the shadow file:
pwauth auth required /lib/security/pam_unix.so
pwauth account required /lib/security/pam_unix.so
You can authenticate from a SMB server if you have installed the pam_smb
package (available from http://samba.org/samba). On Solaris 2.6, the
/etc/pam.conf lines to do this would be something like:
pwauth auth required /lib/security/pam_smb_auth.so.1
You may want a "nolocal" flag on that line if you are authenticating from
a remote server, or you may not. Note that if you configure pam_smb so
that root access isn't required, you should be able to use mod_auth_pam
instead of mod_auth_external and pwauth and get faster authentications.
(6) Test the pwauth program. As root, you can just run the thing, type
in a login (hit return) and a password (hit return), and then check
the exit code (in csh: "echo $status" in sh: "echo $?"). It should
be 0 for correct login/password pairs and 1 otherwise.
(7) Install it in some sensible place (say, /usr/local/libexec/pwauth).
Unless you are doing SHADOW_NONE, it should be suid-root, so that
it has the necessary access to read the shadow file. That is, the
file should be owned by root, and you should do "chmod o+s pwauth" on
it. After you've installed it, it is worth su-ing to whatever account
your httpd runs under and testing pwauth again from that account. This
should confirm that all the uid's and suid-bits are configured correctly.
On OpenBSD the master password database is readable (but not writable)
to group _shadow, so you should be able to install it sgid to group
"_shadow" instead of suid root. However, I've not been able to make
this work.
(8) If you are using pwauth with mod_auth_external, add to the Apache
server configuration file directives that give the full path to
wherever you installed this program and designate the pipe method
for communicating with the authenticator. For example:
AddExternalAuth pwauth /usr/local/libexec/pwauth
SetExternalAuthMethod pwauth pipe
It is possible to use this module with the "environment" method
instead of the "pipe" method by compiling it with the ENV_METHOD
flag defined, however this has security problems on some Unixes.
(9) Put an .htaccess file in whatever directory you want to protect.
(For .htaccess files to work, you may need to change some
"AllowOverride None" directives in your httpd.conf file into
"AllowOverride AuthConfig" directives).
A typical .htaccess file using mod_auth_external would look like:
AuthType Basic
AuthName Your-Site-Name
AuthExternal pwauth
require valid-user
A typical .htaccess file using mod_authnz_external would look like:
AuthType Basic
AuthName Your-Site-Name
AuthBasicProvider external
AuthExternal pwauth
require valid-user
Alternately, you can put a <Directory> block with the same directives
in your httpd.conf file.
(10) Test it by trying to access a file in the protected directory with your
web browser.
If it fails to accept correct logins, then check Apache's error log file.
This should give some messages explaining why authentication failed.
If it was unable to execute pwauth, check that the pathnames and
permissions are all correct.
If it says that pwauth failed, it will give the numeric return code.
The numeric return codes returned by pwauth are as follows:
0 - Login OK.
1 - Nonexistant login or (for some configurations) incorrect
password.
2 - Incorrect password (for some configurations).
3 - Uid number is below MIN_UNIX_UID value configured in config.h.
4 - Login ID has expired.
5 - Login's password has expired.
6 - Logins to system have been turned off (usually by /etc/nologin
file).
7 - Limit on number of bad logins exceeded.
50 - pwauth was not run with real uid SERVER_UID. If you get this
error code, you probably have SERVER_UID set incorrectly in
pwauth's config.h file.
51 - pwauth was not given a login & password to check. The means
the passing of data from mod_auth_external to pwauth is messed
up. Most likely one is trying to pass data via environment
variables, while the other is trying to pass data via a pipe.
52 - one of several possible internal errors occured. You'll have
to read the source code to figure these out.
53 - pwauth was not able to read the password database. Usually
this means it is not running as root. (PAM and login.conf
configurations will return 1 in this case.)
If you want to allow users of only certain groups to login, the perl
"unixgroup" command included in this directory will do the job, though not
very efficiently. If you are using mod_authnz_external, a better approach
is to use mod_authz_unixgroup. This will not only allow you to restrict
logins to users in particular groups, but restrict access to individual
files based on group ownership of the files, if used with the standard Apache
module mod_authz_owner.
