"Fossies" - the Fresh Open Source Software Archive

Member "mod_auth_ldap/README" (15 Apr 2000, 7964 Bytes) of package /linux/www/apache_httpd_modules/old/mod_auth_ldap-0.5.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 mod_auth_ldap
    2 =============
    3 
    4 Version 0.5
    5 by Alexander Mayrhofer (axelm+ldap@nona.net)
    6 
    7 sha1 algarithm originally by Steve Reid
    8 BindAsUser patch contributed by John-Mark Gurney
    9 
   10 LDAP authentication module for Apache web server (http://www.apache.org/).
   11 
   12 This module allows you to authenticate User against an LDAP tree. It is based 
   13 on mod_auth_dbm. 
   14 
   15 For a history of the module, see the CHANGES file. You can get the latest
   16 version of this module at http://nona.net/software/ldap/
   17 
   18 Compile with Apache
   19 ==================
   20 
   21 Prerequisites
   22 
   23 First, you need of course both Apache and mod_auth_ldap source archives. 
   24 If you can't find Apache on your favourite ftp archive, give www.apache.org
   25 a try. mod_auth_ldap is available at the URL above. Additionally, you will 
   26 need having LDAP libraries installed, if you don't already have them, the 
   27 chances are high that you may not have found what you were looking for when 
   28 you downloaded this file. Check out www.openldap.org for a free LDAP 
   29 implementation. Finally, you do of course need a working build environment 
   30 on your machine.
   31 
   32 Unpacking the stuff
   33 
   34 Unpack Apache as usual, and change into it's "modules" directory:
   35 
   36    % gzip -dc ../path/to/archive/apache_1.3.6.tar.gz | tar -xv<BR>
   37    ...
   38    % cd apache_1.3.6/src/modules
   39 
   40 Then, unpack the mod_auth_ldap archive into the modules directory, e.g.
   41 
   42    % gzip -dc ../path/to/archive/mod_auth_ldap-0.5.tar.gz | tar -xv
   43 
   44 Configuring, Building, Installing
   45 
   46 Change into the newly created "mod_auth_ldap" directory, and configure the 
   47 module itself (some parts of the sha algorithm are endian-dependent, and 
   48 endianess is not checked by the Apache configure script, so the
   49 module comes with it's own autoconf script).
   50 
   51    % cd mod_auth_ldap; ./configure
   52 
   53 Now it's time to choose your favorite apache Config options, and additionally
   54  activate the LDAP authentication module. 
   55 
   56    % cd ../../..; ./configure --prefix=/var/apps/apache \
   57    --activate-module=src/modules/mod_auth_ldap/mod_auth_ldap.c
   58 
   59 After Apache has been configured to your choice, make and install it as usual:
   60 
   61    % make
   62    ...
   63    % make install
   64 
   65 Configuring the module
   66 ======================
   67 
   68 Next step after installing the mod_auth_ldap-enabled Apache is to configure 
   69 it for operation. We'll not talk about general Apache configuration issues, 
   70 please refer to the Apache documentation for that. This page focuses on the
   71 directives introduced by mod_auth_ldap and associated standard directives.
   72 
   73 Let's say that we'd like to protect the Location "/internal" on our server, 
   74 and use a LDAP directory to store the user's credentials. We'd start by 
   75 adding the following lines to our httpd.conf:
   76 
   77    <Location "/internal">
   78    AuthName "very confidential information"
   79    AuthType Basic
   80 
   81 .. as we would do for any other type of password protection with Apache. 
   82 Now we tell mod_auth_ldap where it can reach our LDAP server(s) and how to 
   83 bind to the directory:
   84 
   85    AuthLDAPHosts "ldapserver otherserver:1234"
   86 
   87 You can specify more than one LDAP server (as the line above shows), if 
   88 you're doing this, multiple hosts have to be seperated by spaces. If one of
   89 the LDAP daemons doesn't listen on the standard port (389), you can add the
   90 port number as shown above. Of course, you can also use FQDN's and IP 
   91 addresses.
   92 
   93 By default, mod_auth_ldap tries to bind anonymously to the LDAP directory. 
   94 If you want the module to use specific credentials for binding, you can do 
   95 that by specifying them in the config section, e.g.: 
   96 
   97    AuthLDAPBindDN "reader=web,type=access,o=nonanet,c=at"
   98    AuthLDAPBindPassword abc123
   99 
  100 Warning! Keep in mind that anyone being able to read those credentials may
  101 be able to use them to gain unauthorized access to your LDAP directory. 
  102 Don't forget to double-check the permissions on the config file.
  103 
  104 There's a third method in binding to the directory available: Using the 
  105 credentials supported by the browser. If you add lines like the following
  106 ones to the config:
  107 
  108    AuthLDAPBindAsUser on
  109    AuthLDAPBaseDN "type=luser,o=nonanet,c=at"
  110    AuthLDAPUserKey lusername
  111 
  112 ... the module will construct a DN like 
  113 "lusername=&lt;username&gt;,type=luser,o=nonanet,c=at", and try to bind to 
  114 the directory using that DN and the browser-supported passwort. If that 
  115 succeeds, no more password checks are being done, and the browser supported
  116 credentials are believed to be correct.
  117 
  118 If we don't use "AuthLDAPBindAsUser" (and therefore didn't add the above 
  119 lines to the config file), we'll now have to tell the module where and how 
  120 to find the user's credentials in the LDAP directory. If all your users are 
  121 at the same level of the directory (e.g. exactly one level below 
  122 "type=luser,o=nonanet,c=at"), and they all have the same key in their 
  123 RDN (e.g. "webuser=<username>", the story is rather simple:
  124 
  125    AuthLDAPBaseDN "type=luser,o=nonanet,c=at"
  126    AuthLDAPSearchScope base
  127    AuthLDAPUserKey webuser
  128    AuthLDAPPassKey webpassword
  129 
  130 (The last line above tells the module that the user's password is stored in
  131 the attribute named "webpassword". The module will search below 
  132 "webuser=<username>,type=luser,o=nonanet,c=at", in other words, it can 
  133 directly "hit" the entry, which is fast, but sometimes not flexible enough. 
  134 
  135 Imagine, all your users are still below the same base DN as above, but some 
  136 of them have different RDN's. For example, there may be one department 
  137 storing all their users using the RDN "surname=<name>", maybe another
  138 department chose "extension=<number>". If all of those entries have their 
  139 web credentials stored in the same attributes (e.g. "webuser" and 
  140 "webpassword" again), you will have to change one line of the config 
  141 snippet above:
  142 
  143    AuthLDAPSearchScope onelevel
  144 
  145 If your users are *not* at exactly on level below the base DN, but scattered
  146 through a specific subtree, you can finally use:
  147 
  148    AuthLDAPSearchScope subtree
  149 
  150 Again, all those users need to have their credentials in the same attributes,
  151 e.g. once again "webuser" and "webpassword". We go now into comparing the 
  152 password supplied by the browser against the value from the user's node in
  153 the LDAP directory.
  154 
  155 If we're using AuthLDAPBindAsUser, the password check is being skipped, 
  156 because the password has already been checked (hopefully) by the LDAP server.
  157 For clear text password strings (generally a very bad idea), you don't have
  158 to add anything to the configuration. If your password strings are crypted, 
  159 you'll have to add
  160 
  161    AuthLDAPCryptPasswords on
  162 
  163 to your config snippet. Please be aware, that if you have crypted passwords 
  164 in the directory, and don't set this option to "on", users will be able to
  165 authenticate successfully using the crypted(!) password string which my 
  166 not be what you want... ;-)
  167 
  168 There is a third alternative: use scheme prefixed passwords as described in 
  169 RFC 2307. This seems to be the preferred method to store passwords in 
  170 Netscape's directory server. You can enable scheme prefixed passwords by 
  171 setting
  172 
  173    AuthLDAPSchemePrefix on
  174 
  175 (Pretty straight forward, isn't it? ;-) mod_auth_ldap will then be able to 
  176 check passwords prefixed with "{crypt}" (Un*X crypt) and "{sha}" (Base64 
  177 encodced SHA1 digests as described in FIPS-180-1). Case of the prefix 
  178 strings doesn't matter.
  179 
  180 Ok, we've finally checked the user's password, we can open the gates... 
  181 Expect if only members of specific groups are permitted to enter. In this 
  182 case, we need to tell mod_auth_ldap the name of the attribute listing the 
  183 user's memberships, e.g. by adding:
  184 
  185    AuthLDAPGroupKey webgroup
  186 
  187 and listing the user's groups comma separated, e.g. 
  188 
  189    <Limit GET POST>
  190    require valid-user
  191    </Limit>
  192 
  193 or
  194 
  195 <Limit GET POST>
  196 require group beerdrinking
  197 </Limit>
  198 
  199 before you close the Location with
  200 
  201 </Location>
  202 
  203 Bug reports, patches
  204 ====================
  205 
  206 In case you found any bug, have a question, or did enhance the module, please
  207 drop me a mail at
  208 
  209    axelm+ldap@nona.net
  210 
  211 Your message will usually be read and answered within 2 days.
  212 
  213 
  214 Alex Mayrhofer