source: squid-ssl/trunk/fuentes/helpers/basic_auth/LDAP/basic_ldap_auth.8 @ 5495

Last change on this file since 5495 was 5495, checked in by Juanma, 2 years ago

Initial release

File size: 10.3 KB
Line 
1.if !'po4a'hide' .TH basic_ldap_auth 8 "14 January 2005"
2.
3.SH NAME
4basic_ldap_auth \- LDAP authentication helper for Squid
5.
6.SH SYNOPSIS
7.if !'po4a'hide' .B basic_ldap_auth
8.if !'po4a'hide' .B \-b\ \"
9base DN
10.if !'po4a'hide' .B \"\ [\-u
11attribute
12.if !'po4a'hide' .B ]\ [
13options
14.if !'po4a'hide' .B ]\ [
15LDAP server name
16.if !'po4a'hide' .B [:
17port
18.if !'po4a'hide' .B ]|
19URI
20.if !'po4a'hide' .B ]...
21.br
22.if !'po4a'hide' .B basic_ldap_auth
23.if !'po4a'hide' .B \-b\ \"
24base DN
25.if !'po4a'hide' .B \"\ \-f\ \"
26LDAP search filter
27.if !'po4a'hide' .B \"\ [
28options
29.if !'po4a'hide' .B ]\ [
30LDAP server name
31.if !'po4a'hide' .B [:
32port
33.if !'po4a'hide' .B ]|
34URI
35.if !'po4a'hide' .B ]...
36.
37.SH DESCRIPTION
38.B basic_ldap_auth
39allows Squid to connect to a LDAP directory to
40validate the user name and password of Basic HTTP authentication.
41LDAP options are specified as parameters on the command line,
42while the username(s) and password(s) to be checked against the
43LDAP directory are specified on subsequent lines of input to the
44helper, one username/password pair per line separated by a space.
45.PP
46As expected by the basic authentication construct of Squid, after
47specifying a username and password followed by a new line, this
48helper will produce either
49.B OK
50or
51.B ERR
52on the following line to show if the specified credentials are correct
53according to the LDAP directory.
54.PP
55The program has two major modes of operation. In the default mode
56of operation the users DN is constructed using the base DN and
57user attribute. In the other mode of operation a search
58filter is used to locate valid user DN's below the base DN.
59.
60.SH OPTIONS
61.if !'po4a'hide' .TP 12
62.if !'po4a'hide' .B "\-b basedn"
63.B REQUIRED.
64Specifies the base DN under which the users are located.
65.
66.if !'po4a'hide' .TP
67.if !'po4a'hide' .B "\-f filter"
68LDAP search
69.B filter
70to locate the user DN. Required if the users
71are in a hierarchy below the base DN, or if the login name is
72not what builds the user specific part of the users DN.
73.br
74The search filter can contain up to 15 occurrences of
75.B %s
76which will be replaced by the username, as in
77.B "\"uid\=%s\""
78for RFC2037 directories. For a detailed description of LDAP search
79filter syntax see RFC2254.
80.br
81Will crash if other
82.B %
83values than
84.B %s
85are used, or if more than 15
86.B %s
87are used.
88.
89.if !'po4a'hide' .TP
90.if !'po4a'hide' .B "\-u userattr"
91Specifies the name of the DN attribute that contains the username/login.
92Combined with the base DN to construct the users DN when no search filter
93is specified (
94.B \-f
95option). Defaults to
96.B uid
97.br
98.B Note:
99This can only be done if all your users are located directly under
100the same position in the LDAP tree and the login name is used for naming
101each user object. If your LDAP tree does not match these criterias or if
102you want to filter who are valid users then you need to use a search filter
103to search for your users DN (
104.B \-f
105option).
106.
107.if !'po4a'hide' .TP
108.if !'po4a'hide' .B "\-U passwordattr"
109Use
110.I ldap_compare
111instead of
112.I ldap_simple_bind
113to verify the users password.
114.B passwordattr
115is the LDAP attribute storing the users password.
116.
117.if !'po4a'hide' .TP
118.if !'po4a'hide' .B "\-s base|one|sub"
119Search scope when performing user DN searches specified
120by the
121.B \-f
122option. Defaults to
123.B sub
124.br
125.IP
126.B base
127object only,
128.IP
129.B one
130level below the base object or
131.IP
132.BR sub tree
133below the base object
134.
135.if !'po4a'hide' .TP
136.if !'po4a'hide' .B "\-D binddn \-w password"
137The DN and password to bind as while performing searches. Required by the
138.B \-f
139flag if the directory does not allow anonymous searches.
140.br
141As the password needs to be printed in plain text in your Squid configuration
142it is strongly recommended to use a account with minimal associated privileges.
143This to limit the damage in case someone could get hold of a copy of your
144Squid configuration file.
145.
146.if !'po4a'hide' .TP
147.if !'po4a'hide' .B "\-D binddn \-W secretfile "
148The DN and the name of a file containing the password
149to bind as while performing searches.
150.br
151Less insecure version of the former parameter pair with two advantages:
152The password does not occur in the process listing,
153and the password is not being compromised if someone gets the squid
154configuration file without getting the secretfile.
155.
156.if !'po4a'hide' .TP
157.if !'po4a'hide' .B \-P
158Use a persistent LDAP connection. Normally the LDAP connection
159is only open while validating a username to preserve resources
160at the LDAP server. This option causes the LDAP connection to
161be kept open, allowing it to be reused for further user
162validations. Recommended for larger installations.
163.
164.if !'po4a'hide' .TP
165.if !'po4a'hide' .B \-O
166Only bind once per LDAP connection. Some LDAP servers do not
167allow re-binding as another user after a successful
168.I ldap_bind.
169The use of this option always opens a new connection for each
170login attempt. If combined with the
171.B \-P
172option for persistent
173LDAP connection then the connection used for searching for the
174user DN is kept persistent but a new connection is opened
175to verify each users password once the DN is found.
176.
177.if !'po4a'hide' .TP
178.if !'po4a'hide' .B \-R
179Do not follow referrals
180.
181.if !'po4a'hide' .TP
182.if !'po4a'hide' .B "\-a never|always|search|find"
183when to dereference aliases. Defaults to
184.B never
185.IP
186.B never
187dereference aliases (default),
188.B always
189dereference aliases, only while
190.B search ing
191or only to
192.B find
193the base object.
194.
195.if !'po4a'hide' .TP
196.if !'po4a'hide' .B "\-H ldap_uri
197Specity the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries).
198Servers can also be specified last on the command line.
199.
200.if !'po4a'hide' .TP
201.if !'po4a'hide' .B "\-h ldap_server"
202Specify the LDAP server to connect to. Servers can also be specified last
203on the command line.
204.
205.if !'po4a'hide' .TP
206.if !'po4a'hide' .B "\-p ldap_port"
207Specify an alternate TCP port where the LDAP server is listening if
208other than the default LDAP port 389. Can also be specified within the
209server specification by using servername:port syntax.
210.
211.if !'po4a'hide' .TP
212.if !'po4a'hide' .B "\-v 2|3"
213LDAP protocol version. Defaults to
214.B 3
215if not specified.
216.
217.if !'po4a'hide' .TP
218.if !'po4a'hide' .BI \-Z
219Use TLS encryption
220.
221.if !'po4a'hide' .TP
222.if !'po4a'hide' .B "\-S certpath"
223Enable LDAP over SSL (requires Netscape LDAP API libraries)
224.
225.if !'po4a'hide' .TP
226.if !'po4a'hide' .B "\-c connect_timeout"
227Specify
228.B timeout
229used when connecting to LDAP servers (requires
230Netscape LDAP API libraries)
231.
232.if !'po4a'hide' .TP
233.if !'po4a'hide' .B "\-t search_timeout"
234Specify time limit on LDAP search operations
235.
236.if !'po4a'hide' .TP
237.if !'po4a'hide' .B \-d
238Debug mode where each step taken will get reported in detail.
239Useful for understanding what goes wrong if the results is
240not what is expected.
241.
242.SH CONFIGURATION
243For directories using the RFC2307 layout with a single domain, all
244you need to specify is usually the base DN under where your users
245are located and the server name:
246.IP
247.if !'po4a'hide' .RS
248.if !'po4a'hide' .B basic_ldap_auth -b "ou=people,dc=your,dc=domain" ldapserver
249.if !'po4a'hide' .RE
250.PP
251If you have sub\-domains then you need to use a search filter approach
252to locate your user DNs as these can no longer be constructed directly
253from the base DN and login name alone:
254.IP
255.if !'po4a'hide' .RS
256.if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver
257.if !'po4a'hide' .RE
258.PP
259And similarly if you only want to allow access to users having a
260specific attribute
261.IP
262.if !'po4a'hide' .RS
263.if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialattribute=value))" ldapserver
264.if !'po4a'hide' .RE
265.PP
266Or if the user attribute of the user DN is
267.B "cn"
268instead of
269.B "uid"
270and you do not want to have to search for the users then you could use something
271like the following example for Active Directory:
272.IP
273.if !'po4a'hide' .RS
274.if !'po4a'hide' .B basic_ldap_auth -u cn -b "cn=Users,dc=your,dc=domain" ldapserver
275.if !'po4a'hide' .RE
276.PP
277If you want to search for the user DN and your directory does not allow
278anonymous searches then you must also use the
279.B \-D
280and
281.B \-w
282flags to specify a user DN and password to log in as to perform the searches, as in the
283following complex Active Directory example
284.IP
285.if !'po4a'hide' .RS
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
287.if !'po4a'hide' .RE
288.
289.PP
290.B NOTE:
291When constructing search filters it is strongly recommended to test the filter
292using
293.B ldapsearch
294before you attempt to use
295.B basic_ldap_auth.
296This to verify that the filter matches what you expect.
297.
298.SH AUTHOR
299This 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>
302.
303This manual is written by
304.if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
305.
306.SH COPYRIGHT
307.PP
308 * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
309 *
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.
313.PP
314This program and documentation is copyright to the authors named above.
315.PP
316Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
317.
318.SH QUESTIONS
319Questions 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>
322.PP
323Or to your favorite LDAP list/friend if the question is more related to
324LDAP than Squid.
325.
326.SH REPORTING BUGS
327Bug reports need to be made in English.
328See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
329.PP
330Report bugs or bug fixes using http://bugs.squid-cache.org/
331.PP
332Report serious security bugs to
333.I Squid Bugs <squid-bugs@squid-cache.org>
334.PP
335Report ideas for new improvements to the
336.I Squid Developers mailing list
337.if !'po4a'hide' <squid-dev@squid-cache.org>
338.
339.SH SEE ALSO
340.if !'po4a'hide' .BR squid "(8), "
341.if !'po4a'hide' .BR ldapsearch "(1), "
342.if !'po4a'hide' .BR GPL "(7), "
343.br
344Your favorite LDAP documentation.
345.br
346.BR RFC2254 " - The String Representation of LDAP Search Filters,"
347.br
348The Squid FAQ wiki
349.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
350.br
351The Squid Configuration Manual
352.if !'po4a'hide' http://www.squid-cache.org/Doc/config/
353
Note: See TracBrowser for help on using the repository browser.