mod_auth_ldap configuration

Next step after installing the mod_auth_ldap-enabled Apache is to configure it for operation. We'll not talk about general Apache configuration issues, please refer to the Apache documentation for that. This page focuses on the directives introduced by mod_auth_ldap and associated standard directives.

Let's say that we'd like to protect the Location "/internal" on our server, and use a LDAP directory to store the user's credentials. We'd start by adding the following lines to our httpd.conf:

<Location "/internal">
AuthName "very confidential information"
AuthType Basic 

.. as we would do for any other type of password protection with Apache. Now we tell mod_auth_ldap where it can reach our LDAP server(s) and how to bind to the directory:

AuthLDAPHosts "ldapserver otherserver:1234"

You can specify more than one LDAP server (as the line above shows), if you're doing this, multiple hosts have to be seperated by spaces. If one of the LDAP daemons doesn't listen on the standard port (389), you can add the port number as shown above. Of course, you can also use FQDN's and IP addresses.

By default, mod_auth_ldap tries to bind anonymously to the LDAP directory. If you want the module to use specific credentials for binding, you can do that by specifying them in the config section, e.g.:

AuthLDAPBindDN "reader=web,type=access,o=nonanet,c=at"
AuthLDAPBindPassword abc123

Warning! Keep in mind that anyone being able to read those credentials may be able to use them to gain unauthorized access to your LDAP directory. Don't forget to double-check the permissions on the config file.

There's a third method in binding to the directory available: Using the credentials supported by the browser. If you add lines like the following ones to the config:

AuthLDAPBindAsUser on
AuthLDAPBaseDN "type=luser,o=nonanet,c=at"
AuthLDAPUserKey lusername

... the module will construct a DN like "lusername=username,type=luser,o=nonanet,c=at", and try to bind to the directory using that DN and the browser-supported passwort. If that succeeds, no more password checks are being done, and the browser supported credentials are believed to be correct.

If we don't use "AuthLDAPBindAsUser" (and therefore didn't add the above lines to the config file), we'll now have to tell the module where and how to find the user's credentials in the LDAP directory. If all your users are at the same level of the directory (e.g. exactly one level below "type=luser,o=nonanet,c=at"), and they all have the same key in their RDN (e.g. "webuser=username", the story is rather simple:

AuthLDAPBaseDN "type=luser,o=nonanet,c=at"
AuthLDAPSearchScope base
AuthLDAPUserKey webuser
AuthLDAPPassKey webpassword

(The last line above tells the module that the user's password is stored in the attribute named "webpassword"). The module will search below "webuser=username,type=luser,o=nonanet,c=at", in other words, it can directly "hit" the entry, which is fast, but sometimes not flexible enough.

Imagine, all your users are still below the same base DN as above, but some of them have different RDN's. For example, there may be one department storing all their users using the RDN "surname=name", maybe another department chose "extension=number". If all of those entries have their web credentials stored in the same attributes (e.g. "webuser" and "webpassword" again), you will have to change one line of the config snippet above:

AuthLDAPSearchScope onelevel

If your users are not at exactly on level below the base DN, but scattered through a specific subtree, you can finally use:

AuthLDAPSearchScope subtree

Again, all those users need to have their credentials in the same attributes, e.g. once again "webuser" and "webpassword". We go now into comparing the password supplied by the browser against the value from the user's node in the LDAP directory. If we're using AuthLDAPBindAsUser, the password check is being skipped, because the password has already been checked (hopefully) by the LDAP server. For clear text password strings (generally a very bad idea), you don't have to add anything to the configuration. If your password strings are crypted, you'll have to add

AuthLDAPCryptPasswords on

to your config snippet. Please be aware, that if you have crypted passwords in the directory, and don't set this option to "on", users will be able to authenticate successfully using the crypted(!) password string which my not be what you want... ;-)

There is a third alternative: use scheme prefixed passwords as described in RFC 2307. This seems to be the preferred method to store passwords in Netscape's directory server. You can enable scheme prefixed passwords by setting

AuthLDAPSchemePrefix on

(Pretty straight forward, isn't it? ;-) mod_auth_ldap will then be able to check passwords prefixed with "{crypt}" (Un*X crypt) and "{sha}" (Base64 encodced SHA1 digests as described in FIPS-180-1). Case of the prefix strings doesn't matter.

Ok, we've finally checked the user's password, we can open the gates... Except if only members of specific groups are permitted to enter. In that case, we need to tell mod_auth_ldap the name of the attribute listing the user's memberships, e.g. by adding:

AuthLDAPGroupKey webgroup

and listing the user's groups comma separated, e.g. "development,bofh,beerdrinking". Don't forget to add the

<Limit GET POST>
require valid-user
</Limit>

or

<Limit GET POST>
require group beerdrinking
</Limit>

before you close the Location with

</Location>