1 .if !'po4a'hide' .TH basic_ldap_auth 8 "14 January 2005"
4 basic_ldap_auth \- LDAP authentication helper for Squid
7 .if !'po4a'hide' .B basic_ldap_auth
8 .if !'po4a'hide' .B \-b\ \"
10 .if !'po4a'hide' .B \"\ [\-u
12 .if !'po4a'hide' .B ]\ [
14 .if !'po4a'hide' .B ]\ [
16 .if !'po4a'hide' .B [:
18 .if !'po4a'hide' .B ]|
20 .if !'po4a'hide' .B ]...
22 .if !'po4a'hide' .B basic_ldap_auth
23 .if !'po4a'hide' .B \-b\ \"
25 .if !'po4a'hide' .B \"\ \-f\ \"
27 .if !'po4a'hide' .B \"\ [
29 .if !'po4a'hide' .B ]\ [
31 .if !'po4a'hide' .B [:
33 .if !'po4a'hide' .B ]|
35 .if !'po4a'hide' .B ]...
39 allows Squid to connect to a LDAP directory to
40 validate the user name and password of Basic HTTP authentication.
41 LDAP options are specified as parameters on the command line,
42 while the username(s) and password(s) to be checked against the
43 LDAP directory are specified on subsequent lines of input to the
44 helper, one username/password pair per line separated by a space.
46 As expected by the basic authentication construct of Squid, after
47 specifying a username and password followed by a new line, this
48 helper will produce either
52 on the following line to show if the specified credentials are correct
53 according to the LDAP directory.
55 The program has two major modes of operation. In the default mode
56 of operation the users DN is constructed using the base DN and
57 user attribute. In the other mode of operation a search
58 filter is used to locate valid user DN's below the base DN.
61 .if !'po4a'hide' .TP 12
62 .if !'po4a'hide' .B "\-b basedn"
64 Specifies the base DN under which the users are located.
67 .if !'po4a'hide' .B "\-f filter"
70 to locate the user DN. Required if the users
71 are in a hierarchy below the base DN, or if the login name is
72 not what builds the user specific part of the users DN.
74 The search filter can contain up to 15 occurrences of
76 which will be replaced by the username, as in
78 for RFC2037 directories. For a detailed description of LDAP search
79 filter syntax see RFC2254.
85 are used, or if more than 15
90 .if !'po4a'hide' .B "\-u userattr"
91 Specifies the name of the DN attribute that contains the username/login.
92 Combined with the base DN to construct the users DN when no search filter
99 This can only be done if all your users are located directly under
100 the same position in the LDAP tree and the login name is used for naming
101 each user object. If your LDAP tree does not match these criterias or if
102 you want to filter who are valid users then you need to use a search filter
103 to search for your users DN (
108 .if !'po4a'hide' .B "\-U passwordattr"
113 to verify the users password.
115 is the LDAP attribute storing the users password.
118 .if !'po4a'hide' .B "\-s base|one|sub"
119 Search scope when performing user DN searches specified
130 level below the base object or
133 below the base object
136 .if !'po4a'hide' .B "\-D binddn \-w password"
137 The DN and password to bind as while performing searches. Required by the
139 flag if the directory does not allow anonymous searches.
141 As the password needs to be printed in plain text in your Squid configuration
142 it is strongly recommended to use a account with minimal associated privileges.
143 This to limit the damage in case someone could get hold of a copy of your
144 Squid configuration file.
147 .if !'po4a'hide' .B "\-D binddn \-W secretfile "
148 The DN and the name of a file containing the password
149 to bind as while performing searches.
151 Less insecure version of the former parameter pair with two advantages:
152 The password does not occur in the process listing,
153 and the password is not being compromised if someone gets the squid
154 configuration file without getting the secretfile.
157 .if !'po4a'hide' .B \-P
158 Use a persistent LDAP connection. Normally the LDAP connection
159 is only open while validating a username to preserve resources
160 at the LDAP server. This option causes the LDAP connection to
161 be kept open, allowing it to be reused for further user
162 validations. Recommended for larger installations.
165 .if !'po4a'hide' .B \-O
166 Only bind once per LDAP connection. Some LDAP servers do not
167 allow re-binding as another user after a successful
169 The use of this option always opens a new connection for each
170 login attempt. If combined with the
172 option for persistent
173 LDAP connection then the connection used for searching for the
174 user DN is kept persistent but a new connection is opened
175 to verify each users password once the DN is found.
178 .if !'po4a'hide' .B \-R
179 Do not follow referrals
182 .if !'po4a'hide' .B "\-a never|always|search|find"
183 when to dereference aliases. Defaults to
187 dereference aliases (default),
189 dereference aliases, only while
196 .if !'po4a'hide' .B "\-H ldap_uri
197 Specity the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries).
198 Servers can also be specified last on the command line.
201 .if !'po4a'hide' .B "\-h ldap_server"
202 Specify the LDAP server to connect to. Servers can also be specified last
206 .if !'po4a'hide' .B "\-p ldap_port"
207 Specify an alternate TCP port where the LDAP server is listening if
208 other than the default LDAP port 389. Can also be specified within the
209 server specification by using servername:port syntax.
212 .if !'po4a'hide' .B "\-v 2|3"
213 LDAP protocol version. Defaults to
218 .if !'po4a'hide' .BI \-Z
222 .if !'po4a'hide' .B "\-S certpath"
223 Enable LDAP over SSL (requires Netscape LDAP API libraries)
226 .if !'po4a'hide' .B "\-c connect_timeout"
229 used when connecting to LDAP servers (requires
230 Netscape LDAP API libraries)
233 .if !'po4a'hide' .B "\-t search_timeout"
234 Specify time limit on LDAP search operations
237 .if !'po4a'hide' .B \-d
238 Debug mode where each step taken will get reported in detail.
239 Useful for understanding what goes wrong if the results is
240 not what is expected.
243 For directories using the RFC2307 layout with a single domain, all
244 you need to specify is usually the base DN under where your users
245 are located and the server name:
248 .if !'po4a'hide' .B basic_ldap_auth -b "ou=people,dc=your,dc=domain" ldapserver
251 If you have sub\-domains then you need to use a search filter approach
252 to locate your user DNs as these can no longer be constructed directly
253 from the base DN and login name alone:
256 .if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver
259 And similarly if you only want to allow access to users having a
263 .if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialattribute=value))" ldapserver
266 Or if the user attribute of the user DN is
270 and you do not want to have to search for the users then you could use something
271 like the following example for Active Directory:
274 .if !'po4a'hide' .B basic_ldap_auth -u cn -b "cn=Users,dc=your,dc=domain" ldapserver
277 If you want to search for the user DN and your directory does not allow
278 anonymous searches then you must also use the
282 flags to specify a user DN and password to log in as to perform the searches, as in the
283 following complex Active Directory example
286 .if !'po4a'hide' .B basic_ldap_auth -P -R -b "dc=your,dc=domain" -D "cn=squid,cn=users,dc=your,dc=domain" -w "secretsquidpassword" -f "(&(userPrincipalName=%s)(objectClass=Person))" activedirectoryserver
291 When constructing search filters it is strongly recommended to test the filter
294 before you attempt to use
296 This to verify that the filter matches what you expect.
299 This program is written by
300 .if !'po4a'hide' .I Glenn Newton <gnewton@wapiti.cisti.nrc.ca>
301 .if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
303 This manual is written by
304 .if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
308 * Copyright (C) 1996-2017 The Squid Software Foundation and contributors
310 * Squid software is distributed under GPLv2+ license and includes
311 * contributions from numerous individuals and organizations.
312 * Please see the COPYING and CONTRIBUTORS files for details.
314 This program and documentation is copyright to the authors named above.
316 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
319 Questions on the usage of this program can be sent to the
320 .I Squid Users mailing list
321 .if !'po4a'hide' <squid-users@squid-cache.org>
323 Or to your favorite LDAP list/friend if the question is more related to
327 Bug reports need to be made in English.
328 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
330 Report bugs or bug fixes using http://bugs.squid-cache.org/
332 Report serious security bugs to
333 .I Squid Bugs <squid-bugs@squid-cache.org>
335 Report ideas for new improvements to the
336 .I Squid Developers mailing list
337 .if !'po4a'hide' <squid-dev@squid-cache.org>
340 .if !'po4a'hide' .BR squid "(8), "
341 .if !'po4a'hide' .BR ldapsearch "(1), "
342 .if !'po4a'hide' .BR GPL "(7), "
344 Your favorite LDAP documentation.
346 .BR RFC2254 " - The String Representation of LDAP Search Filters,"
349 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
351 The Squid Configuration Manual
352 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/