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\ \(dq 9base DN 10.if !'po4a'hide' .B \(dq\ [\-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\ \(dq 24base DN 25.if !'po4a'hide' .B \(dq\ \-f\ \(dq 26LDAP search filter 27.if !'po4a'hide' .B \(dq\ [ 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 "\(dquid\=%s\(dq" 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 criteria 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 during a 190.B search 191or only to 192.B find 193the base object. 194. 195.if !'po4a'hide' .TP 196.if !'po4a'hide' .B "\-H ldap_uri 197Specify 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-2021 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@lists.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@lists.squid-cache.org> 334.PP 335Report ideas for new improvements to the 336.I Squid Developers mailing list 337.if !'po4a'hide' <squid-dev@lists.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 354