[mod_auth_ldap Release 2.4.2]

--muquit@muquit.com, Nov-03-2005 (released 3.07)
--muquit@muquit.com, Jun-27-2004 (released 3.01)

Please read the file README3.11.txt
(May-29-2006)

Table of Contents

• Background
• Download
  • Download source (Unix) (optional for MS NT/2000)
  • Download DLL (MS NT/2000)
• Steps to compile and install
  • Compiling in with apache (Unix)
  • Compiling as Dynamic Shared Object (Unix)
  • Compiling as DLL in Windows MS NT/2000 (Optional)
  • Install compiled/supplied DLL in Windows MS NT/2000
  • Read Apache INSTALL file
  • Prepare httpd.conf or .htaccess
  • Start Apache
• Environment variables
• Explanation of the directives
• Web publishing
• Passing control to lower-level modules
• How you can help
• ChangeLog

Background
LDAP is a client-server protocol for accessing a directory service. LDAP server can be used as a central point for user authentication over the network. LDAP is the industry standard for directory access and embraced by companies such as IBM, Netscape, Novell, Microsoft etc.

This module can be used for http basic authentication using the user data stored in a Lightweight Directory Access Protocol (LDAP) server. I wrote it in September of 1998. I think the module is simple and clean! I'd like to know what you think though.

Before compiling the module, you need to compile and install LDAP libraries. Above all, you must have a working LDAP server. You can use Netscape Directory server or free Open LDAP server. I found Netscape LDAP server is significantly faster and robust, however OpenLDAP server is getting better everyday. Netscape directory server SDK can be used with Open LDAP server and vice versa (netscape SDK has few extra functions).

Download
If you're on Linux/Unix, you must download the source. If you're on MS NT/2000, you can download and use the supplied dll.

Steps to compile and install

1. (All platforms) Install/configure a LDAP server. Choices:
   - Netscape Directory server (very easy) or
   - Open LDAP server (not hard if you read instructions)
   - Microsoft Active Directory in Win 2000.
   - Novell NDS with LDAP gateway.
   Any LDAP server should work though.

2. (Linux/Unix) Install a LDAP C SDK. Choices:
   - If you installed Open LDAP server, you already have it.
   - The other choice is Netscape Directory C SDK

   If you already have Apache compiled with Dynamic Shared Object (DSO) support, please skip the next section and go to the section Compiling as Dynamic Shared Object.

3. Compiling in with apache (Linux/Unix)
   
   • Download Apache from: http://www.apache.org/httpd.html

   • Extract apache (as of today the current version is 1.3.27)

     $ gunzip < apache_1.3.27.tar.gz | tar xvf -

     Apache will be extracted in the directory apache_1.3.27.

   • Extract Auth module

     $ gunzip < mod_auth_ldap.tar.gz | tar xvf -

     Auth module will be extracted in the directory modauthldap. Look at the file modauthldap/mod_auth_ldap.c. By default, debugging for the module is OFF. If you are installing the module for the very first time, it's a good idea to turn the debugging on. You can turn on debugging by un-commenting the line

     #define DEBUG_LDAP 1

     If you compile with debugging on, watch the apache error_log file. Do not forget to comment it out and recompile, re-install apache, when you're sure that the module works or you server error log will have lots of messages.

   • At the shell prompt, type:

     $ cd apache_1.3.27 $ mv ../modauthldap ./src/modules/ldap $ ./configure --activate-module=src/modules/ldap/mod_auth_ldap.c $ make $ make install

4. Compiling as Dynamic Shared Object (Linux/Unix)
   To use this method, you must have apache compiled and installed with DSO support. Stock RedHat Linux comes with Apache compiled with DSO support.
   • Extract Auth module

     $ gunzip < mod_auth_ldap.tar.gz | tar xvf -

   • Find out where the program apxs is installed. I assume it is in /usr/local/apache/bin. At the shell prompt type:
     

     $ cd modauthldap $ /usr/local/apache/bin/apxs -I/usr/local/include \ -L/usr/local/lib -lldap -llber -i -a -c mod_auth_ldap.c

     In Solaris, you may not need -llber.

     If you installed your LDAP headers and libraries elsewhere, edit -I/usr/local/include and -L/usr/local/lib and specify the correct paths. apxs will compile, copy the module to the correct place and modify httpd.conf file for you.

5. Compiling as DLL in Windows MS NT/2000
   You do not need to compile the module in MS NT or 2000. An already compiled DLL is supplied. Howerver, if you need to coimpile it for some reason, you'll need MS Visual C++ (I used MS Visual C++ 6.0) which is NOT free. Download the source, extract it inside src/modules directory of Apache source.. Open a command shell and type:

   cd mod_auth_ldap nmake -f makefile.wnt

   The DLL modu_auth_ldap.dll will be created.

6. Install compiled/supplied DLL in Windows MS NT/2000
   Download and extract the zip file containing the module (unless you compiled the DLL yourself). The supplied zip file has the following files:

    mod_auth_ldap_dll/
    mod_auth_ldap_dll/mod_auth_ldap.dll        - non debug version
    mod_auth_ldap_dll/mod_auth_ldap.dll.debug  - debug version
    mod_auth_ldap_dll/README
   

   The debug version of the module writes debug messages in the server error_log file. So you should use this module first, when you're sure that the module works properly, replace it with the non debug version.

   Copy the debug version of the module in the Apache modules directory first, e.g.
   copy mod_auth_ldap.dll.debug c:/Apache/modules/mod_auth_ldap.dll

   Modify the file httpd.conf and put the following lines:

   LoadModule ldap_auth_module modules/mod_auth_ldap.dll
   

   Then put the following line under the line ClearModuleList

   AddModule mod_auth_ldap.c
   

   Note: When you're sure that the module works properly, replace the installed module with the non debug version or error_log file will have lots of debug messages.

7. Read the INSTALL file comes with apache to configure and start apache.

8. Now I assume you finished installing and testing Apache. It's time to make use of the LDAP authentication module. If you want to protect a directory say foo in the server's document root, put a section like below in the httpd.conf file:

   <Directory "/usr/local/apache/htdocs/foo"> #<Directory "C:/Apache/htdocs/foo"> Options Indexes FollowSymLinks AllowOverride None order allow,deny allow from all AuthName "RCS Staff only" AuthType Basic LDAP_Server ldap.fccc.edu LDAP_Port 389 Base_DN "o=Fox Chase Cancer Center,c=US" #Bind_DN "uid=admin,o=Fox Chase Cancer Center,c=US" #Bind_Pass "secret" UID_Attr uid #require valid-user require user muquit foo bar "john doe" #require roomnumber "123 Center Building" #require filter "(&(telephonenumber=1234)(roomnumber=123))" #require group cn=rcs,ou=Groups </Directory>

   DO NOT forget to edit the above section. Make sure you change the LDAP_Server to your one, change the Base_DN and require attribute as well.

   Note, you can use <Location "/foo"> instead of <Directory "/usr/local/apache/htdocs/foo"> I prefer to use Directory, because I don't have to wonder around to find out what the real directory is.

   Or create a file .htaccess with the following contents in the directory you want to protect:

   AuthName "RCS Staff only" AuthType Basic LDAP_Server ldap.fccc.edu LDAP_Port 389 Base_DN "o=Fox Chase Cancer Center,c=US" UID_Attr uid #require valid-user require user muquit foo bar "john doe" #require roomnumber "123 Center Building" #require filter "(&(telephonenumber=1234)(roomnumber=123))" #require group cn=rcs,ou=Groups

   Note: In order to make .htaccess work, make sure you allow it with AllowOverride option. By default it is OFF.

9. Stop and start apache (Linux/Unix):

   /usr/local/apache/bin/apachectl stop /usr/local/apache/bin/apachectl start

   MS NT/2000 users, please follow the Apache doc on how to start/stop the server. If you installed apache as service, you can stop/start from command line as:

   If there is no syntax error in apache configuration file/s, (or if the module loaded successfully in NT/2000) server will start withoug any error in error_log file.

   net stop "Apache" net start "Apache"

Environment variables
At this time the following environ variables are set if the authentication is successful which can be checked from CGI program etc:

    LDAP_USER
    MOD_AUTH_LDAP_VERSION

Explanation of the directives

Web publishing
You can use this module for authentication with netscape communicator (or other browsers which supports HTTP PUT method) to publish (File->Publish... menu) web pages. But you need to compile apache with mod_put module first. Now lets say, you want to publish in the directory publish at the server document root, put a section like below in the httpd.conf file:

Passing control to lower-level modules
If you're not familiar with Apache, you might be wondering what it means by passing authentication and authorization to lower level modules. If apache is compiled with this module, it will try to authenticate user/group all from LDAP server. But some times you might want to authenticate access to a directory by other means e.g. by a file or database. If you want to do so, you've to use the directive AuthLDAPAuthoritative no first and then use the usual means to specify the alternative authentication mechanism. Here're we'll show an example using .htaccess file in some directory:

The file /usr/local/apache/.htpasswd contains userid:crypted_password in each line, for example:

Make sure the file .htpasswd is not accessible via a web browser. Now, if the user muquit does not exist in the LDAP server or authentication failed in LDAP then the module will use the userid and password from .htpasswd file to authenticate the user. Similarly group authentication can be passed to lower level modules using require group and AuthGroupFile directives.

How you can help
You always can help by contributing code, reporting bugs etc. I want to implement the following things but not getting time to do so. You probably can help to do this:

• Add a filter directive in httpd.conf file. This will allow authentication on arbitrary condition.
  Example:

    require filter "(&(ou=foo dept)(telephonenumber=1234))"

  Status: done (Apr-14-2001)

• Allow multiple ldap servers in httpd.conf file.
  Example:

    LDAP_Server "ldap.muquit.com:389 ldap.foo.edu:489"

If you find this module useful, please let me know. Bug reports, suggestions, patches are always welcome.

Enjoy!

ChangeLog

Release 2.4.2

• Acts properly if empty user/password is specified.
  (Jun-01-2003)

  Release 2.4.1

• Source was in DOS format. Sorry :(
  (Oct-08-2002)
• Replaced the call free(dn) with ldap_memfree(dn). It was dying on Windows 2000 if compiled with iPlanet C SDK 5.08.
  (Sep-24-2002)

• closing connection message is finally put inside DEBUG_LDAP directive.
  (Sep-24-2002)

  Release 2.4

• Added filter option in the server config file, so that any arbitrary condition can be used on a user authentication.
  (Apr-14-2001)

• The directive require user can have space in ithe values.
  Example: require user foo "john doe" bar
  (Apr-14-2001)

  Release 2.3

• Makefile.wnt for NT/2000 was missing.
  (Apr-11-2001)

• Added Bind_DN and Bind_Pass. Requested by Martin Zardecki to use the module with Windows 2000 Active Directory (AD). Thanks to Martin for testing the module with Win 2000 AD. Thanks to Alexis for some tips on Win 2000 AD.
  (Mar-15-2001)

  Release 2.2

• Sets another environment variable MOD_AUTH_LDAP_VERSION if the authentication is successfull.
  (Mar-15-2001)

• Compiled the DLL on Windows NT (no porting was necessary). Linked with some old version of netscape LDAP C SDK (I think 2.0).
  (Mar-05-2001)

• Possible memory leak plugged. result var in ldap_search_s() was not freed by calling ldap_msgfree().
  (Feb-05-2001)

• Added a blind bind to see if the user can bind with a dn of 'uid_attr=uid, base_dn' if not we just keep going with the old scheme. This allows for people to authenticate through a non-anonymous directory server if it's set up consistently. Also added a little better error when no user is found during the dn search. Patch sent by david@giffin.org.
  (Feb-03-2001) Note: it's not needed anymore because binging can be done by specifying Bind_DN and Bind_Pass. (Mar-15-2001)

• If authenticated successfully an environment variable called LDAP_USER is set. Requested by Ben Brewer.
  (Feb-03-2001)

• Was not passing authentication and authorization to lower lever modules with 'require group' when AuthLDAPAuthoritative was set to no. The patch was sent by Matt Magri.
  (Oct-28-2000)

• replaced ap_getword() and my rmallws() calls with ap_getword_white(). Replaced ap_getword() and rmallws() calls for attributes with ap_getword_conf() as suggested by Mark OLear, mgolear@ilstu.edu. The reason to use ap_getword_conf() was: if say require ou "Foo bar" is used, ap_geword() was tokenizing the string to Foo and bar, but we want to consider "Foo bar" as one string.
  (Feb-10-2000)

• Changed "require group" to give the partial DN (Base DN is appended). Also fixed a bug when using multible groeps it would free() the user "dn" to early. Thanks to Take.Vos@cable.a2000.nl.
  (Sep-20-1999)

• If LDAP_Server directive is not specified in the server config file, give control back. The default LDAP server was localhost, now it's NULL. Thanks to Gregory C. Falck, greg.falck@lmco.com.
  (Aug-20-1999)

• Added AuthLDAPAuthoritative directive so that control can be passed to a lower level module if userid does not exist in LDAP server. Thanks to Gregory C. Falck, greg.falck@lmco.com.
  (Aug-19-1999)

• Added instruction to compile as DSO. Requested by feuer@his.com
  (Jul-31-1999).

• wrote src/modules/ldap/mod_auth_ldap.module script to automate compiling with apache 1.3.x
  (Jul-3001999)

• Released Jul-6-1999.

• First cut Sep-5-1998.

(Page Last updated: Sun Mar 31 01:59:56 2013 GMT

URL of this page: http://www.muquit.com/muquit/software/mod_auth_ldap/mod_auth_ldap.html