1basic_ldap_auth(8)          System Manager's Manual         basic_ldap_auth(8)
2
3
4

NAME

6       basic_ldap_auth - LDAP authentication helper for Squid
7

SYNOPSIS

9       basic_ldap_auth  -b "  base  DN  " [-u  attribute  ] [ options ] [ LDAP
10       server name [: port ]| URI ]...
11       basic_ldap_auth -b " base DN " -f " LDAP search filter " [ options  ] [
12       LDAP server name [: port ]| URI ]...
13

DESCRIPTION

15       basic_ldap_auth allows Squid to connect to a LDAP directory to validate
16       the user name and password of Basic HTTP authentication.  LDAP  options
17       are  specified as parameters on the command line, while the username(s)
18       and password(s) to be checked against the LDAP directory are  specified
19       on  subsequent lines of input to the helper, one username/password pair
20       per line separated by a space.
21
22       As expected by the basic authentication construct of Squid, after spec‐
23       ifying a username and password followed by a new line, this helper will
24       produce either OK or ERR on the following line to show if the specified
25       credentials are correct according to the LDAP directory.
26
27       The  program  has  two major modes of operation. In the default mode of
28       operation the users DN is  constructed  using  the  base  DN  and  user
29       attribute.  In  the  other mode of operation a search filter is used to
30       locate valid user DN's below the base DN.
31

OPTIONS

33       -b basedn   REQUIRED.  Specifies the base DN under which the users  are
34                   located.
35
36       -f filter   LDAP  search  filter to locate the user DN. Required if the
37                   users are in a hierarchy below the base DN, or if the login
38                   name is not what builds the user specific part of the users
39                   DN.
40                   The search filter can contain up to 15  occurrences  of  %s
41                   which  will be replaced by the username, as in "uid=%s" for
42                   RFC2037 directories. For a  detailed  description  of  LDAP
43                   search filter syntax see RFC2254.
44                   Will  crash  if other % values than %s are used, or if more
45                   than 15 %s are used.
46
47       -u userattr Specifies the name of the DN attribute  that  contains  the
48                   username/login.  Combined with the base DN to construct the
49                   users DN when no search filter is specified (  -f  option).
50                   Defaults to uid
51                   Note:  This  can only be done if all your users are located
52                   directly under the same position in the LDAP tree  and  the
53                   login  name  is  used  for naming each user object. If your
54                   LDAP tree does not match these criteria or if you  want  to
55                   filter  who  are  valid users then you need to use a search
56                   filter to search for your users DN ( -f option).
57
58       -U passwordattr
59                   Use ldap_compare instead of ldap_simple_bind to verify  the
60                   users password.  passwordattr is the LDAP attribute storing
61                   the users password.
62
63       -s base|one|sub
64                   Search scope when performing user DN searches specified  by
65                   the -f option. Defaults to sub
66
67                   base object only,
68
69                   one level below the base object or
70
71                   subtree below the base object
72
73       -D binddn -w password
74                   The  DN  and password to bind as while performing searches.
75                   Required by the -f flag if the  directory  does  not  allow
76                   anonymous searches.
77                   As  the  password needs to be printed in plain text in your
78                   Squid configuration it is strongly  recommended  to  use  a
79                   account  with minimal associated privileges.  This to limit
80                   the damage in case someone could get hold of a copy of your
81                   Squid configuration file.
82
83       -D binddn -W secretfile
84                   The  DN  and  the name of a file containing the password to
85                   bind as while performing searches.
86                   Less insecure version of the former parameter pair with two
87                   advantages:  The  password  does  not  occur in the process
88                   listing, and the password is not being compromised if some‐
89                   one  gets  the squid configuration file without getting the
90                   secretfile.
91
92       -P          Use a persistent LDAP connection. Normally the LDAP connec‐
93                   tion  is  only open while validating a username to preserve
94                   resources at the LDAP server. This option causes  the  LDAP
95                   connection  to  be  kept open, allowing it to be reused for
96                   further user validations. Recommended for larger  installa‐
97                   tions.
98
99       -O          Only  bind  once  per LDAP connection. Some LDAP servers do
100                   not allow re-binding as another  user  after  a  successful
101                   ldap_bind.   The use of this option always opens a new con‐
102                   nection for each login attempt. If  combined  with  the  -P
103                   option  for  persistent LDAP connection then the connection
104                   used for searching for the user DN is kept persistent but a
105                   new connection is opened to verify each users password once
106                   the DN is found.
107
108       -R          Do not follow referrals
109
110       -a never|always|search|find
111                   when to dereference aliases. Defaults to never
112
113                   never dereference  aliases  (default),  always  dereference
114                   aliases,  only  during  a  search  or only to find the base
115                   object.
116
117       -H ldap_uri Specify the LDAP server to connect to by LDAP URI (requires
118                   OpenLDAP libraries).  Servers can also be specified last on
119                   the command line.
120
121       -h ldap_server
122                   Specify the LDAP server to connect to. Servers can also  be
123                   specified last on the command line.
124
125       -p ldap_port
126                   Specify an alternate TCP port where the LDAP server is lis‐
127                   tening if other than the default LDAP port 389. Can also be
128                   specified  within the server specification by using server‐
129                   name:port syntax.
130
131       -v 2|3      LDAP protocol version. Defaults to 3 if not specified.
132
133       -Z          Use TLS encryption
134
135       -S certpath Enable LDAP over SSL (requires Netscape LDAP API libraries)
136
137       -c connect_timeout
138                   Specify  timeout  used  when  connecting  to  LDAP  servers
139                   (requires Netscape LDAP API libraries)
140
141       -t search_timeout
142                   Specify time limit on LDAP search operations
143
144       -d          Debug  mode  where  each  step  taken  will get reported in
145                   detail.  Useful for understanding what goes  wrong  if  the
146                   results is not what is expected.
147

CONFIGURATION

149       For  directories using the RFC2307 layout with a single domain, all you
150       need to specify is usually the base  DN  under  where  your  users  are
151       located and the server name:
152
153              basic_ldap_auth -b ou=people,dc=your,dc=domain ldapserver
154
155       If  you  have sub-domains then you need to use a search filter approach
156       to locate your user DNs as these can no longer be constructed  directly
157       from the base DN and login name alone:
158
159              basic_ldap_auth -b dc=your,dc=domain -f uid=%s ldapserver
160
161       And  similarly  if you only want to allow access to users having a spe‐
162       cific attribute
163
164              basic_ldap_auth -b  dc=your,dc=domain  -f  (&(uid=%s)(specialat‐
165              tribute=value)) ldapserver
166
167       Or if the user attribute of the user DN is cn instead of uid and you do
168       not want to have to search for the users then you could  use  something
169       like the following example for Active Directory:
170
171              basic_ldap_auth -u cn -b cn=Users,dc=your,dc=domain ldapserver
172
173       If you want to search for the user DN and your directory does not allow
174       anonymous searches then you must also use the -D and -w flags to  spec‐
175       ify  a user DN and password to log in as to perform the searches, as in
176       the following complex Active Directory example
177
178              basic_ldap_auth    -P     -R     -b     dc=your,dc=domain     -D
179              cn=squid,cn=users,dc=your,dc=domain  -w  secretsquidpassword  -f
180              (&(userPrincipalName=%s)(objectClass=Person))   activedirectory‐
181              server
182
183       NOTE:  When  constructing  search filters it is strongly recommended to
184       test  the  filter  using  ldapsearch  before   you   attempt   to   use
185       basic_ldap_auth.   This  to  verify  that  the  filter matches what you
186       expect.
187

AUTHOR

189       This program is written by Glenn  Newton  <gnewton@wapiti.cisti.nrc.ca>
190       Henrik Nordstrom <hno@squid-cache.org> This manual is written by Henrik
191       Nordstrom <hno@squid-cache.org>
192
194        * Copyright (C) 1996-2021 The Squid Software Foundation and  contribu‐
195       tors
196        *
197        * Squid software is distributed under GPLv2+ license and includes
198        * contributions from numerous individuals and organizations.
199        * Please see the COPYING and CONTRIBUTORS files for details.
200
201       This program and documentation is copyright to the authors named above.
202
203       Distributed under the GNU General Public License (GNU GPL) version 2 or
204       later (GPLv2+).
205

QUESTIONS

207       Questions on the usage of this program can be sent to the  Squid  Users
208       mailing list <squid-users@lists.squid-cache.org>
209
210       Or to your favorite LDAP list/friend if the question is more related to
211       LDAP than Squid.
212

REPORTING BUGS

214       Bug reports  need  to  be  made  in  English.   See  http://wiki.squid-
215       cache.org/SquidFaq/BugReporting for details of what you need to include
216       with your bug report.
217
218       Report bugs or bug fixes using http://bugs.squid-cache.org/
219
220       Report serious security bugs  to  Squid  Bugs  <squid-bugs@lists.squid-
221       cache.org>
222
223       Report  ideas for new improvements to the Squid Developers mailing list
224       <squid-dev@lists.squid-cache.org>
225

SEE ALSO

227       squid(8), ldapsearch(1), GPL(7),
228       Your favorite LDAP documentation.
229       RFC2254 - The String Representation of LDAP Search Filters,
230       The Squid FAQ wiki http://wiki.squid-cache.org/SquidFaq
231       The Squid Configuration Manual http://www.squid-cache.org/Doc/config/
232
233
234
235
236                                14 January 2005             basic_ldap_auth(8)
Impressum