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