When you need to deploy a custom, weird or non typical Auth schema with Apache, knowing about the Auth External module can save you tons of time.
It is is commonly deployed along with pwauth for allowing unix users to authenticate against Apache, but this only one case use. Actually it can be used for almost any Auth setup that you can imagine.
The main idea behind it is very simple and powerful, it delegates Apache authentication on any program or script that you want. Simply it will feed your program with the user/password variables along other interesting variables like IP, cookies, URI, etc. and your program must return zero if the user is allowed to access or non-zero otherwise.
I will show you a simple example.
” I have my home server where I run an LDAP directory with some users and I also have a remote server in a hosting company where I want to allow the users of my LDAP directory to access some https directory protected by the Apache authentication.
Accessing the LDAP directory from the remote server is not an option because I have a firewall protecting it and I can’t/don’t want to do such a thing. And configuring an slave LDAP server on the remote server is even a worse option.”
So here is when Auth external comes to rescue.
On my home server I configure a dummy https virtual host that authenticates users via the local LDAP
<VirtualHost *:443>
SSLEngine on
ServerName dummy-https.homeserver.com
ServerAdmin clopez@igalia.com
TransferLog /var/log/apache2/dummy-https-access.log
ErrorLog /var/log/apache2/dummy-https-error.log
<Directory /var/www/empty>
AuthName Auth
AuthType Basic
AuthBasicProvider ldap
AuthzLDAPAuthoritative On
AuthLDAPURL "ldap://localhost/dc=homeserver,dc=com?uid"
AuthLDAPGroupAttribute uniqueMember
AuthLDAPGroupAttributeIsDN On
Require valid-user
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
And on the remote server I just implement a very simple script that will read from stdin an user and password strings and will try to establish an https connection with my apache home server using the supplied credentials. It will return zero if it can get the connection, otherwise will return 1
#! /bin/sh read user read password /usr/bin/curl -f -u "$user":"$password" https://dummy-https.homeserver.com >/dev/null 2>&1 || exit 1 exit 0
I saved this script as /usr/local/bin/home-ssl.sh and now I will install the auth external module and will enable it
apt-get install libapache2-mod-authnz-external a2enmod authnz_external
Note: for Debian Lenny grab the backport’s package
And now I will configure the Apache virtual host with the auth external authentication:
<VirtualHost *:443>
SSLEngine on
ServerName securearea.hostingprovider.com
ServerAdmin clopez@igalia.com
TransferLog /var/log/apache2/securearea.hostingprovider-access.log
ErrorLog /var/log/apache2/securearea.hostingprovider-error.log
DocumentRoot /var/www/securearea
<Directory /var/www/securearea>
AuthType Basic
AuthName "Restricted"
AuthBasicProvider external
AuthExternal home-ssl
require valid-user
</Directory>
AddExternalAuth home-ssl /usr/local/bin/home-ssl.sh
SetExternalAuthMethod home-ssl pipe
</VirtualHost>
In summary:
- User access https://securearea.hostingprovider.com/
- Apache@hostingprovider ask user for credentials
- Apache@hostingprovider calls /usr/local/bin/home-ssl.sh and feed it with user credentials
- /usr/local/bin/home-ssl.sh calls Apache@homeserver at https://dummy-https.homeserver.com
- Apache@homeserver ask for user credentials to local LDAP database
- If credentials are correct Apache@homeserver will allow /usr/local/bin/home-ssl.sh to access making it to return zero so the user will be allowed to access securearea at Apache@hostingprovider
Want to write an external authenticator? Here you have a quick howto Enjoy !
