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 attri‐
29       bute.  In the other mode of operation a search filter is used to locate
30       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 ac‐
79                   count  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 op‐
103                   tion  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 ob‐
115                   ject.
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  (re‐
139                   quires 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 de‐
145                   tail.  Useful for understanding what goes wrong if the  re‐
146                   sults 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  lo‐
151       cated 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  ba‐
185       sic_ldap_auth.  This to verify that the filter matches what you expect.
186

AUTHOR

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

QUESTIONS

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

REPORTING BUGS

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

SEE ALSO

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