[mod_auth_ldap Release 2.12 for Apache 2.x]

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

--muquit@muquit.com, May-23-2004

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.09+)
  • Base_DN
  • Bind_DN
  • Bind_Pass
  • UID_Attr
  • UID_Attr_Alt (vailable in v2.08+)
  • Group_Attr (available in v2.08+)
  • SupportNestedGroups (available in v2.08+)
  • LDAP_Debug (available in v2.07+)
  • LDAP_Protocol_Version (available in v2.07+)
  • AuthOnBind (available in v2.12+)
  • Sub_DN (available in v2.12+)
  • LDAP_Persistent (available in v2.12+)
  • Bind_Tries (available in v2.12+)
  • LDAP_Deref (available in v2.07+)
  • LDAP_StartTLS (available in v2.07+)
  • LDAP_CertDbDir (available in v2.07+)
  • require
    • valid-user
    • user
    • filter
    • group
• Configuring for encryption (SSL and TLS)
• Nested groups (vailable in v2.08+)
• 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

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 or directly in path_apache2/bin/apachectl start-up script.

   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.47)

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

        Apache will be extracted in the directory httpd-2.0.47.

      • 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.47 $ sh ../modauth_apache2/mk_withldap --prefix=/usr/local/apache247

        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 #AuthAuthoritative Off AuthName "RCS Staff only" AuthType Basic #AuthOnBind Off #Sub_DNou=CIS,ou=People #LDAP_Persistent On #Bind_Tries 5 #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 #AuthOnBind Off #Sub_DNou=CIS,ou=People #LDAP_Persistent On #Bind_Tries 5 #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"

    LDAP_USER
    MOD_AUTH_LDAP_VERSION