helpers/basic_auth/LDAP/basic_ldap_auth.8

   1 .if !'po4a'hide' .TH basic_ldap_auth 8 "14 January 2005"
   2 .
   3 .SH NAME
   4 .if !'po4a'hide' .B basic_ldap_auth
   5 .if !'po4a'hide' \-
   6 LDAP authentication helper for Squid
   7 .
   8 .SH SYNOPSIS
   9 .if !'po4a'hide' .B basic_ldap_auth
  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 ]\ [
  17 LDAP server name
  18 .if !'po4a'hide' .B [:
  19 port
  20 .if !'po4a'hide' .B ]|
  21 URI
  22 .if !'po4a'hide' .B ]...
  23 .br
  24 .if !'po4a'hide' .B basic_ldap_auth
  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 ]\ [
  32 LDAP server name
  33 .if !'po4a'hide' .B [:
  34 port
  35 .if !'po4a'hide' .B ]|
  36 URI
  37 .if !'po4a'hide' .B ]...
  38 .
  39 .SH DESCRIPTION
  40 .B basic_ldap_auth
  41 allows Squid to connect to a LDAP directory to
  42 validate the user name and password of Basic HTTP authentication.
  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.
  47 .PP
  48 As expected by the basic authentication construct of Squid, after
  49 specifying a username and password followed by a new line, this
  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.
  56 .PP
  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 .
  62 .SH OPTIONS
  63 .if !'po4a'hide' .TP 12
  64 .if !'po4a'hide' .B "\-b basedn"
  65 .B REQUIRED.
  66 Specifies the base DN under which the users are located.
  67 .
  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
  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.
  75 .br
  76 The search filter can contain up to 15 occurrences of
  77 .B %s
  78 which will be replaced by the username, as in
  79 .B "\"uid\=%s\""
  80 for RFC2037 directories. For a detailed description of LDAP search
  81 filter syntax see RFC2254.
  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.
  90 .
  91 .if !'po4a'hide' .TP
  92 .if !'po4a'hide' .B "\-u userattr"
  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
  95 is specified (
  96 .B \-f
  97 option). Defaults to
  98 .B uid
  99 .br
 100 .B Note:
 101 This can only be done if all your users are located directly under
 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
 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
 127 .IP
 128 .B base
 129 object only,
 130 .IP
 131 .B one
 132 level below the base object or
 133 .IP
 134 .BR sub tree
 135 below the base object
 136 .
 137 .if !'po4a'hide' .TP
 138 .if !'po4a'hide' .B "\-D binddn \-w password"
 139 The DN and password to bind as while performing searches. Required by the
 140 .B \-f
 141 flag if the directory does not allow anonymous searches.
 142 .br
 143 As the password needs to be printed in plain text in your Squid configuration
 144 it is strongly recommended to use a account with minimal associated privileges.
 145 This to limit the damage in case someone could get hold of a copy of your
 146 Squid configuration file.
 147 .
 148 .if !'po4a'hide' .TP
 149 .if !'po4a'hide' .B "\-D binddn \-W secretfile "
 150 The DN and the name of a file containing the password
 151 to bind as while performing searches.
 152 .br
 153 Less insecure version of the former parameter pair with two advantages:
 154 The password does not occur in the process listing,
 155 and the password is not being compromised if someone gets the squid
 156 configuration file without getting the secretfile.
 157 .
 158 .if !'po4a'hide' .TP
 159 .if !'po4a'hide' .B \-P
 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.
 165 .
 166 .if !'po4a'hide' .TP
 167 .if !'po4a'hide' .B \-O
 168 Only bind once per LDAP connection. Some LDAP servers do not
 169 allow re-binding as another user after a successful
 170 .I ldap_bind.
 171 The use of this option always opens a new connection for each
 172 login attempt. If combined with the
 173 .B \-P
 174 option for persistent
 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 .
 179 .if !'po4a'hide' .TP
 180 .if !'po4a'hide' .B \-R
 181 Do not follow referrals
 182 .
 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
 187 .IP
 188 .B never
 189 dereference aliases (default),
 190 .B always
 191 dereference aliases, only while
 192 .B search ing
 193 or only to
 194 .B find
 195 the base object.
 196 .
 197 .if !'po4a'hide' .TP
 198 .if !'po4a'hide' .B "\-H ldap_uri
 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.
 201 .
 202 .if !'po4a'hide' .TP
 203 .if !'po4a'hide' .B "\-h ldap_server"
 204 Specify the LDAP server to connect to. Servers can also be specified last
 205 on the command line.
 206 .
 207 .if !'po4a'hide' .TP
 208 .if !'po4a'hide' .B "\-p ldap_port"
 209 Specify an alternate TCP port where the LDAP server is listening if
 210 other than the default LDAP port 389. Can also be specified within the
 211 server specification by using servername:port syntax.
 212 .
 213 .if !'po4a'hide' .TP
 214 .if !'po4a'hide' .B "\-v 2|3"
 215 LDAP protocol version. Defaults to
 216 .B 3
 217 if not specified.
 218 .
 219 .if !'po4a'hide' .TP
 220 .if !'po4a'hide' .BI \-Z
 221 Use TLS encryption
 222 .
 223 .if !'po4a'hide' .TP
 224 .if !'po4a'hide' .B "\-S certpath"
 225 Enable LDAP over SSL (requires Netscape LDAP API libraries)
 226 .
 227 .if !'po4a'hide' .TP
 228 .if !'po4a'hide' .B "\-c connect_timeout"
 229 Specify
 230 .B timeout
 231 used when connecting to LDAP servers (requires
 232 Netscape LDAP API libraries)
 233 .
 234 .if !'po4a'hide' .TP
 235 .if !'po4a'hide' .B "\-t search_timeout"
 236 Specify time limit on LDAP search operations
 237 .
 238 .if !'po4a'hide' .TP
 239 .if !'po4a'hide' .B \-d
 240 Debug mode where each step taken will get reported in detail.
 241 Useful for understanding what goes wrong if the results is
 242 not what is expected.
 243 .
 244 .SH CONFIGURATION
 245 For directories using the RFC2307 layout with a single domain, all
 246 you need to specify is usually the base DN under where your users
 247 are located and the server name:
 248 .IP
 249 .if !'po4a'hide' .RS
 250 .if !'po4a'hide' .B basic_ldap_auth -b "ou=people,dc=your,dc=domain" ldapserver
 251 .if !'po4a'hide' .RE
 252 .PP
 253 If you have sub\-domains then you need to use a search filter approach
 254 to locate your user DNs as these can no longer be constructed directly
 255 from the base DN and login name alone:
 256 .IP
 257 .if !'po4a'hide' .RS
 258 .if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver
 259 .if !'po4a'hide' .RE
 260 .PP
 261 And similarly if you only want to allow access to users having a
 262 specific attribute
 263 .IP
 264 .if !'po4a'hide' .RS
 265 .if !'po4a'hide' .B basic_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialattribute=value))" ldapserver
 266 .if !'po4a'hide' .RE
 267 .PP
 268 Or if the user attribute of the user DN is
 269 .B "cn"
 270 instead of
 271 .B "uid"
 272 and you do not want to have to search for the users then you could use something
 273 like the following example for Active Directory:
 274 .IP
 275 .if !'po4a'hide' .RS
 276 .if !'po4a'hide' .B basic_ldap_auth -u cn -b "cn=Users,dc=your,dc=domain" ldapserver
 277 .if !'po4a'hide' .RE
 278 .PP
 279 If you want to search for the user DN and your directory does not allow
 280 anonymous searches then you must also use the
 281 .B \-D
 282 and
 283 .B \-w
 284 flags to specify a user DN and password to log in as to perform the searches, as in the
 285 following complex Active Directory example
 286 .IP
 287 .if !'po4a'hide' .RS
 288 .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
 289 .if !'po4a'hide' .RE
 290 .
 291 .PP
 292 .B NOTE:
 293 When constructing search filters it is strongly recommended to test the filter
 294 using
 295 .B ldapsearch
 296 before you attempt to use
 297 .B basic_ldap_auth.
 298 This to verify that the filter matches what you expect.
 299 .
 300 .SH AUTHOR
 301 This program is written by
 302 .if !'po4a'hide' .I Glenn Newton <gnewton@wapiti.cisti.nrc.ca>
 303 .if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
 304 .
 305 This manual is written by
 306 .if !'po4a'hide' .I Henrik Nordstrom <hno@squid-cache.org>
 307 .
 308 .SH COPYRIGHT
 309 .PP
 310  * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 311  *
 312  * Squid software is distributed under GPLv2+ license and includes
 313  * contributions from numerous individuals and organizations.
 314  * Please see the COPYING and CONTRIBUTORS files for details.
 315 .PP
 316 This program and documentation is copyright to the authors named above.
 317 .PP
 318 Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
 319 .
 320 .SH QUESTIONS
 321 Questions on the usage of this program can be sent to the
 322 .I Squid Users mailing list
 323 .if !'po4a'hide' <squid-users@squid-cache.org>
 324 .PP
 325 Or to your favorite LDAP list/friend if the question is more related to
 326 LDAP than Squid.
 327 .
 328 .SH REPORTING BUGS
 329 Bug reports need to be made in English.
 330 See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
 331 .PP
 332 Report bugs or bug fixes using http://bugs.squid-cache.org/
 333 .PP
 334 Report serious security bugs to
 335 .I Squid Bugs <squid-bugs@squid-cache.org>
 336 .PP
 337 Report ideas for new improvements to the
 338 .I Squid Developers mailing list
 339 .if !'po4a'hide' <squid-dev@squid-cache.org>
 340 .
 341 .SH SEE ALSO
 342 .if !'po4a'hide' .BR squid "(8), "
 343 .if !'po4a'hide' .BR ldapsearch "(1), "
 344 .if !'po4a'hide' .BR GPL "(7), "
 345 .br
 346 Your favorite LDAP documentation.
 347 .br
 348 .BR RFC2254 " - The String Representation of LDAP Search Filters,"
 349 .br
 350 The Squid FAQ wiki
 351 .if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
 352 .br
 353 The Squid Configuration Manual
 354 .if !'po4a'hide' http://www.squid-cache.org/Doc/config/
 355