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