1basic_ldap_auth(8) System Manager's Manual basic_ldap_auth(8)
2
6 basic_ldap_auth - LDAP authentication helper for Squid
7
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
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 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 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
33 -b basedn REQUIRED. Specifies the base DN under which the users are
34 located.
35 -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 -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 -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 -s base|one|sub
64 Search scope when performing user DN searches specified by
65 the -f option. Defaults to sub
66 base object only,
68 one level below the base object or
70 subtree below the base object
72 -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 -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 -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 -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 -R Do not follow referrals
109 -a never|always|search|find
111 when to dereference aliases. Defaults to never
112 never dereference aliases (default), always dereference
114 aliases, only during a search or only to find the base ob‐
115 ject.
116 -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 -h ldap_server
122 Specify the LDAP server to connect to. Servers can also be
123 specified last on the command line.
124 -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 -v 2|3 LDAP protocol version. Defaults to 3 if not specified.
132 -Z Use TLS encryption
134 -S certpath Enable LDAP over SSL (requires Netscape LDAP API libraries)
136 -c connect_timeout
138 Specify timeout used when connecting to LDAP servers (re‐
139 quires Netscape LDAP API libraries)
140 -t search_timeout
142 Specify time limit on LDAP search operations
143 -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
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 basic_ldap_auth -b ou=people,dc=your,dc=domain ldapserver
154 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 basic_ldap_auth -b dc=your,dc=domain -f uid=%s ldapserver
160 And similarly if you only want to allow access to users having a spe‐
162 cific attribute
163 basic_ldap_auth -b dc=your,dc=domain -f (&(uid=%s)(specialat‐
165 tribute=value)) ldapserver
166 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 basic_ldap_auth -u cn -b cn=Users,dc=your,dc=domain ldapserver
172 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 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 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
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 This program and documentation is copyright to the authors named above.
201 Distributed under the GNU General Public License (GNU GPL) version 2 or
203 later (GPLv2+).
204
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 Or to your favorite LDAP list/friend if the question is more related to
210 LDAP than Squid.
211
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 Report bugs or bug fixes using https://bugs.squid-cache.org/
218 Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-
220 cache.org>
221 Report ideas for new improvements to the Squid Developers mailing list
223 <squid-dev@lists.squid-cache.org>
224
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 14 January 2005 basic_ldap_auth(8)