"Fossies" - the Fresh Open Source Software Archive 
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=<username>,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