[mod_auth_ldap Release 2.9 for Apache 2.x]

(If you're looking for the module for Apache 1.3.x, please read mod_auth_ldap.html)

Table of Contents

• Background
• Download
  • Download source (Unix) (optional for MS Windows)
  • Download DLL (MS Windows)
• Features
• Steps to compile and install
  • Install a LDAP server and C SDK
  • Dynamic Shared Object or Compiling in with Apache?
    • Compiling as Dynamic Shared Object (Unix)
    • Compiling as DLL in MS Windows (Optional)
    • Compiling in with apache (Unix)
  • Install compiled/supplied DLL in Windows
  • Read Apache INSTALL file
  • Prepare httpd.conf or .htaccess
  • Start Apache
• Explanation of the directives
  • AuthLDAPAuthoritative
  • LDAP_Server
  • LDAP_Port
  • LDAP_Connect_Timeout (available in v2.9+)
  • Base_DN
  • Bind_DN
  • Bind_Pass
  • UID_Attr
  • UID_Attr_Alt (vailable in v2.8+)
  • Group_Attr (available in v2.8+)
  • SupportNestedGroups (available in v2.8+)
  • LDAP_Debug (available in v2.7+)
  • LDAP_Protocol_Version (available in v2.7+)
  • LDAP_Deref (available in v2.7+)
  • LDAP_StartTLS (available in v2.7+)
  • LDAP_CertDbDir (available in v2.7+)
  • require
    • valid-user
    • user
    • filter
    • group
• Configuring for encryption (SSL and TLS)
• Nested groups (vailable in v2.8+)
• Environment variables
  • LDAP_USER
  • LDAP_USER_ALT
  • MOD_AUTH_LDAP_VERSION
• Web publishing
• Passing control to lower-level modules
• How you can help
• Frequently Asked Questions
• 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 on September of 1998 for Apache 1.x and ported it to Apache 2.x API on April of 2002. I believe this is the very first LDAP authentication module for Apache 2.x.

I like to 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.

Download

• Download (v 2.9) source: modauthldap_apache2.tar.gz (153560 bytes) (md5=71e3be961f6ec7b306b2bdc8f26110c8)
  (Last updated: Apr-16-2003 )

• Download (v 2.9) DLL for MS Windows: modauthldap_apache2_dll.zip (76487 bytes) (md5=7eaddbbc1f948426d06ad43b8cabb593)
  (compiled with Apache 2.0.45 on Windows 2000 with iPlanet C SDK 5.08 with SSL
  (Last updated: Apr-16-2003 )
  

  Note: You've to get and copy the DLLS to the modules directory from iPlanet C SDK 5.08. I could supply them but I'm not sure about the legal implecation. You must do that or the module will not be loaded by Apache.

Features

• Encryption with SSL or TLS
• Thread safe
• Multi-platform, supports Linux/Unix and Windows
• Easy to compile/install with autoconf in Linux/Unix. Compiled DLL is supplied for MS Windows
• Can be compiled as a DSO or can be compiled-in with Apache
• Authentication can be done on any valid user, a list of users, a ldap filter, a specific attribute of the user, group and nested groups
• Debug messages can be turned on with a directive at run-time
• Bind DN and passord can be specified if the ldap server does not allow anonymous binding
• Sets some environemnt variables after authentication which can be used from CGI scripts etc.
• LDAP protocol version can be specified
• Can be configured to dereference aliases or not
• The attribute to authenticate user is configurable
• The Group attribute is configurable
• etc..

Steps to compile and install

1. Install a LDAP server and C SDK
   • (All platforms) Install/configure a LDAP server. Choices:
     - iPlanet Directory Server (Formerly Netscape Directory Server). or
     - Open LDAP server (free)
     - Microsoft Active Directory in Win 2000.
     - Novell NDS with LDAP gateway.
     - Any LDAP server will work.

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

2. Dynamic Shared Object or Compiling in with Apache?
   There're two ways the module can be compiled:
   1. Compile the module as Loadable Dynamic Shared Object ( DSO ) . In this method the module is a shared library in Unix and a dll in Windows. The module is loaded at startup. If a new module is released you compile it and replace the installed module. I personally prefer this method. In order to use this method, the apache must be compiled with DSO support. To test it, type: httpd -l, the module mod_so must be in the list.

   2. Compiling in the module with apache. In this method, the module becomes the part of the apacache executable. If a new module is relased you've to compile and instlal the apache again. It's a lot of headache, because you may or may not remember the options you used to compile the original apache.
   1. Compiling as Dynamic Shared Object (DSO) (Linux/Unix)
      
      • In order to load this module dynamically, the server must be compiled with DSO support. You can check if your server is compiled with DSO support by typing: /usr/local/apache2/bin/httpd -l The module mod_so.c must be part of the displayed list.

      • Extract Auth module

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

        Auth module will be extracted in the directory modauthldap_apache2.

      • Specify the path of apxs and path of LDAP C SDK with configure script:

        $ ./configure --with-apxs=/usr/local/apache2/bin/apxs \ --with-ldap-dir=/usr/local/iplanet

        You can ignore the following warning:

        *** Warning: Linking the shared library mod_auth_ldap.la against the non-libtool *** objects mod_auth_ldap.o is not portable!

        If the LDAP SDK supports SSL it will be automatically detected. If you do not want to compile with SSL use the flag --with-ssl=no. If your LDAP C SDK is OpenLDAP, and if it is compiled with TLS, it will be detected.

        $ make (su to root if needed) $ make install

        It will compile and install the module, modify the file httpd.conf to load the module at startup.

        Make sure to update LD_LIBRARY_PATH env variable to include LDAP C SDK lib directory in path_apache2/bin/envvars file.

   2. Compiling in with apache (Linux/Unix)
      
      • Download Apache2 from: http://httpd.apache.org

      • Extract apache 2.x (as of today the current version is 2.0.45)

        $ gunzip < httpd-2.0.45.tar.gz | tar xvf -

        Apache will be extracted in the directory httpd-2.0.45.

      • Extract Auth module

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

        Auth module will be extracted in the directory modauthldap_apache2.

      • At the shell prompt, type:

        $ cd modauthldap_apache2 $ ./configure --with-ldap-dir=/usr/local/iplanet

        If the LDAP SDK supports SSL it will be automatically detected. If you do not want to compile with SSL use the flag --with-ssl=no. If your LDAP C SDK is OpenLDAP, and if it is compiled with TLS, it will be detected.

        $ cd ../httpd-2.0.45 $ sh ../modauth_apache2/mk_withldap --prefix=/usr/local/apache244

        You can specify all valid option of apache2 configure. Because the script mk_withldap will call apache2 configure with the options.

        $ make $ ./httpd -l mod_auth_ldap.c must be in the list. (su to root if needed) $ make install

        Make sure to update LD_LIBRARY_PATHenv variable to include LDAP C SDK lib directory in path_apache2/bin/envvars file.

      • 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. However, if you need to compile it for some reason, you'll need MS Visual C++ (I used MS Visual C++ 6.0) which is NOT free. Modify Makefile.win, open a command shell and type:

        nmake -f Makefile.win

        The DLL modu_auth_ldap.dll will be created.

3. 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:

   modauthldap_apache2_dll/ modauthldap_apache2_dll/mod_auth_ldap.dll modauthldap_apache2_dll/README modauthldap_apache2_dll/cert7.db modauthldap_apache2_dll/key3.db modauthldap_apache2_dll/md5.txt

   Note: You've to get and copy the DLLS to the modules directory from iPlanet C SDK 5.08. I could supply them but I'm not sure about the legal implecation. You must do that or the module will not be loaded by Apache.

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

   LoadModule auth_ldap_module modules/mod_auth_ldap.dll

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

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

5. 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/apache2/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_Debug On #LDAP_Protocol_Version 3 #LDAP_Deref NEVER #LDAP_StartTLS On LDAP_Server ldap.fccc.edu LDAP_Port 389 # Connect timeout in seconds #LDAP_Connect_Timeout 3 # If SSL is on, must specify the LDAP SSL port, usually 636 #LDAP_Port 636 #LDAP_CertDbDir /usr/foo/ssl 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 #UID_Attr_Alt "mail" #Group_Attr uniqueMember #SupportNestedGroupsOff #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/apache2/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_Debug On #LDAP_Protocol_Version 3 #LDAP_Deref NEVER #LDAP_StartTLS On LDAP_Server ldap.fccc.edu LDAP_Port 389 # Connect timeout in seconds #LDAP_Connect_Timeout 3 # If SSL is on, must specify the LDAP SSL port, usually 636 #LDAP_Port 636 #LDAP_CertDbDir /usr/foo/ssl Base_DN "o=Fox Chase Cancer Center,c=US" #UID_Attr"mail" UID_Attr_Alt uid #Group_Attr uniqueMember #SupportNestedGroupsOff #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.

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

   $ /usr/local/apache2/bin/apachectl stop $ /usr/local/apache2/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 without any error in error_log file.

   c:\> net stop "Apache2" c:\> net start "Apache2"

Explanation of the directives

Nested Groups
Sometimes it's desirable to authenticate users even if they belong to different groups. And it is not possible to specify multiple groups for the authentication module. In this kind of situation, another main group can be created and other groups can be members of that group. If a user belongs to any of the member group she can be authenticated. Here is an example:

Here the user is authenticated if she is a direct member of the group WebGroup or if she is a member of any the sub-groups which in turn a member of the group WebGroup. Although the user jdoe is not directly member of the main WebGroup but he belongs to group GroupC. If you look at the picture, GroupC is a member of GroupE which is a member of GrooupH, which is a member of GroupG, which is a member of GroupF and finally GroupF is a member of the main group, the WebGroup. So the user jdoe will be authenticated successfully. The user mjane directly belongs to the WebGroup which is typical. The user foo is not directly a member of the main group but the sub-group GroupA is, so he will be authenticated as well.

As you can see, it can be a expensive operation if you've lots of nesting. So by default, this feature is off. You can turn it on with directive SupportNestedGroups On.

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

If the directive UID_Attr_Alt is set.... If you need any other env var to be set, please let me know.

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/apache2/.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, tips, documentation which might help others etc.

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

Enjoy!

Frequently Asked Questions

1. Q. I get a error message like reason: unknown require directive: "xxxxxxx". What's the problem?
   Ans: Use the directive AuthAuthoritative Off

ChangeLog

Release 2.9

• Added the new directive LDAP_Connect_Timeout to timeout the connection in specified seconds. Note: this directive will work only if you compile the module with iPlanet C SDK 5.08.
  (Apr-14-2003).

• Tested with Apache 2.0.45.
  (Apr-14-2003).

  Release 2.8.3
  

• There was still a bug in nested groups code.
  (Mar-14-2003)

  Release 2.8.2
  

• If a user belongs to a sub-group which belongs to a master group, nested group autorization was failing. Thanks to S T for figuring our the scenario and testing the nested group feature. Thanks to Glen Collins for reporting this bug as well.
  (Mar-13-2003)

  Release 2.8.1
  

• Server could crash if ran with Debug on.
  (Mar-12-2003)

  Release 2.8
  

• Released
  (Mar-08-2003)

• Added support for nested groups due to popular demand.
  (Feb-24-2003)

• New attribute UID_Attr_Alt and new environment varaiable LDAP_USER_ALT.
  (Mar-01-2003)

• Env variables were not set in some situations. Thanks to James Saint-Rossy for the patch.
  (Mar-01-2003)

  Release 2.7

• Added FAQ section.
  (Feb-17-2003)

• TLS and SSL support.

• Debugging can be turned on at run time with LDAP_Debug.

• New directives LDAP_Deref (someone contributed the code.. I forgot who it is, please let me know who you are)

• LDAP_Protocol_Version someone contributed the code.. I forgot who it is, please let me know who you are)

• Module is thread safe now (someone contributed the code.. I forgot who it is, please let me know who you are)
  (Feb-03-2003)

  Release 2.6
  

• Source was in DOS format.. sorry :(
  (Oct-08-2002)

• Replaced the call free(dn) with ldap_memfree(dn). Tested with iPlanet C SDK 5.08)
  (Sep-24-2002)

  Release 2.5

• There's no need to modify srclib/apr/APRVARS.in in order to specify the location of LDAP C SDK header files and libraries. It simply can be done by setting env variables CFLAGS and LDFLAGS respectively.
  (May-10-2002)

• Changed version string to 2.5. Tested with Apache 2.0.43
  (May-08-2002)

• Compiled the module in Windows NT/2000.
  (May-06-2002)

• First release for Apache 2.x. I think this is the very first LDAP authentication module released for Apache 2.x. Correct me if I'm wrong.
  (May-05-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.win 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 successful.
  (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 binding 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 multiple groups 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: Thu Apr 17 00:49:47 2003 GMT

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