src/auth/basic/LDAP/basic_ldap_auth.8

   1 .if !'po4a'hide' .TH basic_ldap_auth 8 "14 January 2005"
   2 .
   3 .SH NAME
   4 basic_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
   9 base DN
  10 .if !'po4a'hide' .B \(dq\ [\-u
  11 attribute
  12 .if !'po4a'hide' .B ]\ [
  13 options
  14 .if !'po4a'hide' .B ]\ [
  15 LDAP server name
  16 .if !'po4a'hide' .B [:
  17 port
  18 .if !'po4a'hide' .B ]|
  19 URI
  20 .if !'po4a'hide' .B ]...
  21 .br
  22 .if !'po4a'hide' .B basic_ldap_auth
  23 .if !'po4a'hide' .B \-b\ \(dq
  24 base DN
  25 .if !'po4a'hide' .B \(dq\ \-f\ \(dq
  26 LDAP search filter
  27 .if !'po4a'hide' .B \(dq\ [
  28 options
  29 .if !'po4a'hide' .B ]\ [
  30 LDAP server name
  31 .if !'po4a'hide' .B [:
  32 port
  33 .if !'po4a'hide' .B ]|
  34 URI
  35 .if !'po4a'hide' .B ]...
  36 .
  37 .SH DESCRIPTION
  38 .B basic_ldap_auth
  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.
  45 .PP
  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
  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.
  54 .PP
  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 .
  60 .SH OPTIONS
  61 .if !'po4a'hide' .TP 12
  62 .if !'po4a'hide' .B "\-b basedn"
  63 .B REQUIRED.
  64 Specifies the base DN under which the users are located.
  65 .
  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
  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.
  73 .br
  74 The search filter can contain up to 15 occurrences of
  75 .B %s
  76 which will be replaced by the username, as in
  77 .B "\(dquid\=%s\(dq"
  78 for RFC2037 directories. For a detailed description of LDAP search
  79 filter syntax see RFC2254.
  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.
  88 .
  89 .if !'po4a'hide' .TP
  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
  93 is specified (
  94 .B \-f
  95 option). Defaults to
  96 .B uid
  97 .br
  98 .B Note:
  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 criteria 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 (
 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
 125 .IP
 126 .B base
 127 object only,
 128 .IP
 129 .B one
 130 level below the base object or
 131 .IP
 132 .BR sub tree
 133 below the base object
 134 .
 135 .if !'po4a'hide' .TP
 136 .if !'po4a'hide' .B "\-D binddn \-w password"
 137 The DN and password to bind as while performing searches. Required by the
 138 .B \-f
 139 flag if the directory does not allow anonymous searches.
 140 .br
 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.
 145 .
 146 .if !'po4a'hide' .TP
 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.
 150 .br
 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.
 155 .
 156 .if !'po4a'hide' .TP
 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.
 163 .
 164 .if !'po4a'hide' .TP
 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
 168 .I ldap_bind.
 169 The use of this option always opens a new connection for each
 170 login attempt. If combined with the
 171 .B \-P
 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.
 176 .
 177 .if !'po4a'hide' .TP
 178 .if !'po4a'hide' .B \-R
 179 Do not follow referrals
 180 .
 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
 185 .IP
 186 .B never
 187 dereference aliases (default),
 188 .B always
 189 dereference aliases, only during a
 190 .B search
 191 or only to
 192 .B find
 193 the base object.
 194 .
 195 .if !'po4a'hide' .TP
 196 .if !'po4a'hide' .B "\-H ldap_uri
 197 Specify the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries).
 198 Servers can also be specified last on the command line.
 199 .
 200 .if !'po4a'hide' .TP
 201 .if !'po4a'hide' .B "\-h ldap_server"
 202 Specify the LDAP server to connect to. Servers can also be specified last
 203 on the command line.
 204 .
 205 .if !'po4a'hide' .TP
 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.
 210 .
 211 .if !'po4a'hide' .TP
 212 .if !'po4a'hide' .B "\-v 2|3"
 213 LDAP protocol version. Defaults to
 214 .B 3
 215 if not specified.
 216 .
 217 .if !'po4a'hide' .TP
 218 .if !'po4a'hide' .BI \-Z
 219 Use TLS encryption
 220 .
 221 .if !'po4a'hide' .TP
 222 .if !'po4a'hide' .B "\-S certpath"
 223 Enable LDAP over SSL (requires Netscape LDAP API libraries)
 224 .
 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
 230 Netscape LDAP API libraries)
 231 .
 232 .if !'po4a'hide' .TP
 233 .if !'po4a'hide' .B "\-t search_timeout"
 234 Specify time limit on LDAP search operations
 235 .
 236 .if !'po4a'hide' .TP
 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.
 241 .
 242 .SH CONFIGURATION
 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:
 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
 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:
 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
 259 And similarly if you only want to allow access to users having a
 260 specific 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
 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
 271 like 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
 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
 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
 283 following 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:
 291 When constructing search filters it is strongly recommended to test the filter
 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 .
 298 .SH AUTHOR
 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>
 305 .
 306 .SH COPYRIGHT
 307 .PP
 308  * Copyright (C) 1996-2019 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
 314 This program and documentation is copyright to the authors named above.
 315 .PP
 316 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 317 .
 318 .SH QUESTIONS
 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@lists.squid-cache.org>
 322 .PP
 323 Or to your favorite LDAP list/friend if the question is more related to
 324 LDAP than Squid.
 325 .
 326 .SH REPORTING BUGS
 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
 330 Report bugs or bug fixes using http://bugs.squid-cache.org/
 331 .PP
 332 Report serious security bugs to
 333 .I Squid Bugs <squid-bugs@lists.squid-cache.org>
 334 .PP
 335 Report 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
 344 Your favorite LDAP documentation.
 345 .br
 346 .BR RFC2254 " - The String Representation of LDAP Search Filters,"
 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