Central HTTP Authentication using LDAP

While basic password authentication using a htaccess file is fine for a small number of users, if you have a larger group of regular users it probably makes more sense to start using directory services. In addition to reducing the administration workload when adding, modifying and removing accounts, by centralising the management of user accounts, it also means that there's less chance of important changes not being propagated.

We're going to use LDAP (Lightweight Directory Access Protocol) to do this, so these examples will assume you have OpenLDAP configured and a working directory of users, and an Apache 2.1+ installation.

CONFIGURING THE DIRECTORY
=========================
Essentially the directory shouldn't require any changing. The most straightforward way to implement this would be to have a single container, such as an organizationalUnit object that contains account, simpleSecurityObject objects.

For the purposes of this tutorial we'll assume that this part of the tree is located at ou=Technical Department,dc=lampguru,dc=co,dc=uk

Depending on how the permissions for your directory are set you may require an additional user for Apache to use. This is because in the first step of authentication Apache binds to LDAP in order to search for the user issued. If you have anonymous read access you won't need to do anything - if not you'll simply need to give Apache the credentials of a user to make the initial bind with.

CONFIGURING THE WEB SERVER:
==========================
Install the OpenLDAP client tools so that if you run into problems you can manually test the connection - this'll help you identify any problems that may crop up.

You'll also need to check that you have both mod_ldap and mod_authzn_ldap installed and enabled. To check what modules you have enabled try running apachectl -M, or apache2ctl -M on Debian systems. If both of the modules show up you can skip forward to writing the .htaccess

If the modules didn't show you may find that they are there but not being included - on Red Hat based systems take a look in httpd.conf for lines like the following, make sure that they're uncommented - restart Apache and check again.

LoadModule ldap_module modules/mod_ldap.so
LoadModule authnz_ldap_module modules/mod_authnz_ldap.so

On Debian systems you'll find that the module declarations are moved outside of the main Apache config - instead search for the files ldap.load and authnz_ldap.load in /etc/apache2/modules-available and create symbolic link to it from modules-enabled directory. The following command line demonstrates this.

ln -s /etc/apache2/modules-available/ldap.load /etc/apache2/modules-enabled/ldap.load
ln -s /etc/apache2/modules-available/authnz_ldap.load /etc/apache2/modules-enabled/authnz_ldap.load

If the modules don't exist try searching for them in your distribution's package management system. If you compiled the server yourself you'll need to recompile it with the --enable-ldap and --enable-authnz-ldap ./configure flags - or you can use the --enable-mods-shared='ldap authnz-ldap' if you would prefer them compiled as modules. If you choose to compile them as modules be sure to include them via the config file.

WRITING THE .HTACCESS:
=====================
You should have an Apache installation with both of the LDAP modules enabled now. Writing LDAP authentication into your .htaccess is fairly straightforward, below is all that you will need for a basic setup.

AuthName "Authentication Required (LDAP Backend)"

AuthBasicProvider ldap
AuthLDAPURL ldap://ldap.lampguru.co.uk:389/ou=Technical Department,dc=lampguru,dc=co,dc=uk?uid

AuthType Basic
require valid-user

AuthName can be whatever you would like to appear in the login box and AuthLDAPURL is an LDAP URL identifying the query. An LDAP URL has the following format, although the extensions part isn't used by Apache.

scheme://host:port/distinguished_name?attribute,s?scope?filters?extensions

In our example we define the connection as plain LDAP, on host ldap.lampguru.co.uk using port 389 - in reality we needn't define the port unless we're using a non-default one. The base distinguished name is ou=Technical Department,dc=lampguru,dc=co,dc=uk, the user-names provided will be matched against the uid attribute. For more information about LDAP URLs consult http://www.zytrax.com/books/ldap/ch9/#url

Incidentally, if you require StartTLS add the argument STARTTLS after the URL, like the following.

AuthLDAPURL ldap://ldap.lampguru.co.uk:389/ou=Technical Department,dc=lampguru,dc=co,dc=uk?uid STARTTLS

If to do the initial use lookup you require Apache to bind as a user, you may define the following additional parameters to facilitates this. Obviously you'll need to update this with whatever the user in your directory is, and their password credentials.

AuthLDAPBindDN "cn=Apache Bind User,ou=meta,dc=lampguru,dc=co,dc=uk"
AuthLDAPBindPassword password-for-that-user

If you are using LDAP groups (groupofnames object) in your directory you can enforce that a user must belong to a specific group by switching AuthType to Authoritative, using the ldap-group argument in require and giving it a group distinguished name to check. Here's an example of this.

AuthType Authoritative
require ldap-group cn=Privileged Group,ou=Technical Department,dc=lampguru,dc=co,dc=uk

FURTHER READING:
===============

You can learn more about OpenLDAP here:

http://www.openldap.org/

To learn more about the Apache modules mod_authnz_ldap and mod_ldap consult the following documentation:

http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html
http://httpd.apache.org/docs/2.2/mod/mod_ldap.html