1squid_ldap_auth(8) System Manager's Manual squid_ldap_auth(8)
2
6 squid_ldap_auth - Squid LDAP authentication helper
7
9 squid_ldap_auth -b "base DN" [-u attribute] [options]
10 [ldap_server_name[:port]|URI]...
11 squid_ldap_auth -b "base DN" -f "LDAP search filter" [options]
12 [ldap_server_name[:port]|URI]...
13
15 This helper allows Squid to connect to a LDAP directory to validate the
16 user name and password of Basic HTTP authentication. LDAP options are
17 specified as parameters on the command line, while the username(s) and
18 password(s) to be checked against the LDAP directory are specified on
19 subsequent lines of input to the helper, one username/password pair per
20 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
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 -b basedn (REQUIRED)
33 Specifies the base DN under which the users are located.
34 -f filter
36 LDAP search filter to locate the user DN. Required if the users
37 are in a hierarchy below the base DN, or if the login name is
38 not what builds the user specific part of the users DN.
39 The search filter can contain up to 15 occurrences of %s which
41 will be replaced by the username, as in "uid=%s" for RFC2037
42 directories. For a detailed description of LDAP search filter
43 syntax see RFC2254.
44 -u userattr
46 Specifies the name of the DN attribute that contains the user‐
47 name/login. Combined with the base DN to construct the users DN
48 when no search filter is specified (-f option). Defaults to
49 'uid'
50 Note: This can only be done if all your users are located
52 directly under the same position in the LDAP tree and the login
53 name is used for naming each user object. If your LDAP tree does
54 not match these criterias or if you want to filter who are valid
55 users then you need to use a search filter to search for your
56 users DN (-f option).
57 -U passwordattr
59 Use ldap_compare instead of ldap_simple_bind to verify the users
60 password. passwordattr is the LDAP attribute storing the users
61 password.
62 -s base|one|sub
64 search scope when performing user DN searches specified by the
65 -f option. Defaults to 'sub'.
66 base object only, one level below the base object or subtree
68 below the base object
69 -D binddn -w password
71 The DN and password to bind as while performing searches.
72 Required by the -f flag if the directory does not allow anony‐
73 mous searches.
74 As the password needs to be printed in plain text in your Squid
76 configuration it is strongly recommended to use a account with
77 minimal associated privileges. This to limit the damage in case
78 someone could get hold of a copy of your Squid configuration
79 file.
80 -D binddn -W secretfile
82 The DN and the name of a file containing the password to bind as
83 while performing searches.
84 Less insecure version of the former parameter pair with two
86 advantages: The password does not occur in the process listing,
87 and the password is not being compromised if someone gets the
88 squid configuration file without getting the secretfile.
89 -P Use a persistent LDAP connection. Normally the LDAP connection
91 is only open while validating a username to preserve resources
92 at the LDAP server. This option causes the LDAP connection to be
93 kept open, allowing it to be reused for further user valida‐
94 tions. Recommended for larger installations.
95 -O Only bind once per LDAP connection. Some LDAP servers do not
97 allow re-binding as another user after a successful ldap_bind.
98 The use of this option always opens a new connection for each
99 login attempt. If combined with the -P option for persistent
100 LDAP connection then the connection used for searching for the
101 user DN is kept persistent but a new connection is opened to
102 verify each users password once the DN is found.
103 -R do not follow referrals
105 -a never|always|search|find
107 when to dereference aliases. Defaults to 'never'
108 never dereference aliases (default), always dereference aliases,
110 only while searching or only to find the base object
111 -H ldapuri
113 Specity the LDAP server to connect to by LDAP URI (requires
114 OpenLDAP libraries). Servers can also be specified last on the
115 command line.
116 -h ldapserver
118 Specify the LDAP server to connect to. Servers can also be spec‐
119 ified last on the command line.
120 -p ldapport
122 Specify an alternate TCP port where the ldap server is listening
123 if other than the default LDAP port 389. Can also be specified
124 within the server specificiation by using servername:port syn‐
125 tax.
126 -v 2|3 LDAP protocol version. Defaults to 3 if not specified.
128 -Z Use TLS encryption
130 -Scertpath
132 Enable LDAP over SSL (requires Netscape LDAP API libraries)
133 -cconnect_timeout
135 Specify timeout used when connecting to LDAP servers (requires
136 Netscape LDAP API libraries)
137 -tsearch_timeout
139 Specify time limit on LDAP search operations
140 -d Debug mode where each step taken will get reported in detail.
142 Useful for understanding what goes wrong if the results is not
143 what is expected.
144
146 For directories using the RFC2307 layout with a single domain, all you
147 need to specify is usually the base DN under where your users are
148 located and the server name:
149 squid_ldap_auth -b "ou=people,dc=your,dc=domain" ldapserver
151 If you have sub-domains then you need to use a search filter approach
153 to locate your user DNs as these can no longer be constructed direcly
154 from the base DN and login name alone:
155 squid_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver
157 And similarily if you only want to allow access to users having a spe‐
159 cific attribute
160 squid_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialat‐
162 tribute=value))" ldapserver
163 Or if the user attribute of the user DN is "cn" instead of "uid" and
165 you do not want to have to search for the users then you could use
166 something like the following example for Active Directory:
167 squid_ldap_auth -u cn -b "cn=Users,dc=your,dc=domain" ldapserver
169 If you want to search for the user DN and your directory does not allow
171 anonymous searches then you must also use the -D and -w flags to spec‐
172 ify a user DN and password to log in as to perform the searches, as in
173 the following complex Active Directory example
174 squid_ldap_auth -P -R -b "dc=your,dc=domain" -D
176 "cn=squid,cn=users,dc=your,dc=domain" -w "secretsquidpassword"
177 -f "(&(userPrincipalName=%s)(objectClass=Person))" activedirec‐
178 toryserver
179
181 When constructing search filters it is strongly recommended to test the
182 filter using ldapsearch before you attempt to use squid_ldap_auth. This
183 to verify that the filter matches what you expect.
184
186 This manual page was written by Henrik Nordstrom <hno@squid-cache.org>
187 squid_ldap_auth is written by Glenn Newton <gnew‐
189 ton@wapiti.cisti.nrc.ca> and Henrik Nordstrom <hno@squid-cache.org>
190
192 Will crash if other % values than %s is used in -f, or if more than 15
193 %s is used.
194
196 Any questions on usage can be sent to Squid Users <squid-users@squid-
197 cache.org>, or to your favorite LDAP list/friend if the question is
198 more related to LDAP than Squid.
199
201 Report bugs or bug-fixes to Squid Bugs <squid-bugs@squid-cache.org> or
202 ideas for new improvements to Squid Developers <squid-dev@squid-
203 cache.org>
204
206 ldapsearch(1),
207 Your favorite LDAP documentation
208 RFC2254 - The String Representation of LDAP Search Filters,
209Squid LDAP Auth 14 January 2005 squid_ldap_auth(8)