The last couple of hours I’ve been fighting with Apache 2.2 authentication. I must say, it is really a mess, hard to debug, and very frustrating. Many times I wished for Lighttpd to have SVN/DAV and authentication modules.
The scenario is simple, you have a server that hosts your subversion repository and you with to serve it through HTTPS for security and access control. Subversion repositories can be served through the svn+ssh access method but this is inflexible (you can not control access to certain branches of the repository at least with subversion <= 1.2) and not properly encrypted (AFAIK svn+ssh only encrypts the login/authentification but not the actual data stream) as you need SSH/shell access for every user. So there is only the HTTPS access method left. And only Apache 2 as a server.
Because you need authentication for the subversion access the simplest thing to do is to create UNIX accounts on the server and let Apache authenticate with HTTPAuth over SSL against this database. You would think that the most common UNIX web server would be able to do this out of the box or at least with just one or two configuration knobs. But this is not the case, configuring Apache 2.2 to authenticate against UNIX shadow accounts is a major pain. Quite surprising if you look how easily dovecot (a POP/IMAP mail server, very young in comparison to Apache) does this out of the box.
There are are two recommended ways to do this, PAM (mod_auth_pam2) and using an external provider (mod_authnz_external). Both modules are not core modules and have their problems.
First there is PAM, the Pluggable Authentification Modules. The nice thing about PAM is that (apart from not being under active development any longer) it is itself a pain to configure and debug. Further in order to make mod_auth_pam(2) access to the shadow files you need to either run Apache as root (BIG MISTAKE!) or give the Apache user read access to the shadow files (also not a very good idea!). So after fighting with PAM for some time, I choose to try the second auth module, mod_authnz_external.
Mod_authnz_external hooks into the Apache auth systems and allows you to define external programs that get the username/password combination and return a status code. This way Apache can outsource the authentication process to an external program that has extra privileges and Apache can keep its low security profile. The author of mod_authnz_external ships such an external program, pwauth. Pwauth authenticates against UNIX shadow files or PAM (yea!). Pwauth runs as setuid root in order to do this but this is much better than running Apache as root or give Apache access to the shadow files.
At compile time you tell pwauth which users are allowed to use it (in my case the user www) and which auth backend to use (shadow or PAM). This can be tested like this (in (t)csh):
# sudo -u www pwauth ; echo $status
username
correct_pw
0
# sudo -u www pwauth ; echo $status
username
incorrect_pw
1
#
On FreeBSD the PAM config for pwauth looks like this:
# cat /etc/pam.d/pwauth
auth required pam_unix.so debug
account required pam_unix.so debug
(I thought that the same configuration would work for Apache, but it didn’t.)
When this is working for you, the fun part starts. Telling Apache how to use mod_authnz_external. In theory you just need to load it and explicitly use it in a part. But in reality it depends on other authz/authn modules and conflicts with others. Again not fun to debug. After a long period of trail and error I got it working. Comment out ALL authn/authz modules and load only these:
LoadModule auth_sys_group_module libexec/apache22/mod_auth_sys_group.so
LoadModule authnz_external_module libexec/apache22/mod_authnz_external.so
LoadModule auth_basic_module libexec/apache22/mod_auth_basic.so
LoadModule authz_host_module libexec/apache22/mod_authz_host.so
Now you can use it in your virtual host definitions. An important fact is that you need to redefine the external provider in every virtual host entry as it will not be inherited from the root node.
<VirtualHost *:80>
DocumentRoot "/usr/local/www/example.com/htdocs"
ServerName example.com
<Directory "/usr/local/www/example.com/htdocs">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
<Location />
SSLRequireSSL
AuthType Basic
AuthName "Restricted"
AuthBasicProvider external
AuthExternal pwauth
require valid-user
require group my_group
</Location>
AddExternalAuth pwauth /usr/local/bin/pwauth
SetExternalAuthMethod pwauth pipe
</VirtualHost>
The important entries are the external provides definition with name of “pwauth” just before the closing VirtualHost and the “AuthBasicProvider external && AuthExternal pwauth” inside the Location.
This finally works as wanted. I still can not believe that UNIX auth is so hard with Apache 2.2.
With SSL and mod_dav_svn the virtual host looks like this:
<VirtualHost _default_:443>
DocumentRoot "/usr/local/www/example.com/htdocs"
ServerName example.com:443
<Directory "/usr/local/www/example.com/htdocs">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
</Directory>
SSLEngine on
SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile /etc/ssl/certs/cert.pem
SSLCertificateKeyFile /etc/ssl/private/cert.key
SSLOptions +StdEnvVars +OptRenegotiate
BrowserMatch ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
<Location />
SSLRequireSSL
DAV svn
SVNPath /usr/local/svn/my_repo
AuthType Basic
AuthName "Restricted"
AuthBasicProvider external
AuthExternal pwauth
require valid-user
require group my_group
</Location>
AddExternalAuth pwauth /usr/local/bin/pwauth
SetExternalAuthMethod pwauth pipe
</VirtualHost>
