basic_ldap_auth - LDAP authentication helper for Squid
basic_ldap_auth -bbase DN attribute ] [
options ] [
LDAP server name [:
basic_ldap_auth -bbase DN LDAP search filter options
LDAP server name [:
allows Squid to connect to a LDAP directory to validate
the user name and password of Basic HTTP authentication. LDAP options are
specified as parameters on the command line, while the username(s) and
password(s) to be checked against the LDAP directory are specified on
subsequent lines of input to the helper, one username/password pair per line
separated by a space.
As expected by the basic authentication construct of Squid, after specifying a
username and password followed by a new line, this helper will produce either
on the following line to show if the specified
credentials are correct according to the LDAP directory.
The program has two major modes of operation. In the default mode of operation
the users DN is constructed using the base DN and user attribute. In the other
mode of operation a search filter is used to locate valid user DN's below the
- -b basedn
- REQUIRED. Specifies the base DN under which the
users are located.
- -f filter
- LDAP search filter to locate the user DN. Required
if the users are in a hierarchy below the base DN, or if the login name is
not what builds the user specific part of the users DN.
The search filter can contain up to 15 occurrences of %s which will
be replaced by the username, as in
for RFC2037 directories. For a detailed description of LDAP search
filter syntax see RFC2254.
Will crash if other % values than %s are used, or if more than
15 %s are used.
- -u userattr
- Specifies the name of the DN attribute that contains the
username/login. Combined with the base DN to construct the users DN when
no search filter is specified ( -f option). Defaults to uid
Note: This can only be done if all your users are located directly
under the same position in the LDAP tree and the login name is used for
naming each user object. If your LDAP tree does not match these criterias
or if you want to filter who are valid users then you need to use a search
filter to search for your users DN ( -f option).
- -U passwordattr
- Use ldap_compare instead of ldap_simple_bind
to verify the users password. passwordattr is the LDAP attribute
storing the users password.
- -s base|one|sub
- Search scope when performing user DN searches specified by
the -f option. Defaults to sub
- base object only,
- one level below the base object or
- subtree below the base object
- -D binddn -w password
- The DN and password to bind as while performing searches.
Required by the -f flag if the directory does not allow anonymous
As the password needs to be printed in plain text in your Squid
configuration it is strongly recommended to use a account with minimal
associated privileges. This to limit the damage in case someone could get
hold of a copy of your Squid configuration file.
- -D binddn -W secretfile
- The DN and the name of a file containing the password to
bind as while performing searches.
Less insecure version of the former parameter pair with two advantages: The
password does not occur in the process listing, and the password is not
being compromised if someone gets the squid configuration file without
getting the secretfile.
- Use a persistent LDAP connection. Normally the LDAP
connection is only open while validating a username to preserve resources
at the LDAP server. This option causes the LDAP connection to be kept
open, allowing it to be reused for further user validations. Recommended
for larger installations.
- Only bind once per LDAP connection. Some LDAP servers do
not allow re-binding as another user after a successful ldap_bind.
The use of this option always opens a new connection for each login
attempt. If combined with the -P option for persistent LDAP
connection then the connection used for searching for the user DN is kept
persistent but a new connection is opened to verify each users password
once the DN is found.
- Do not follow referrals
- -a never|always|search|find
- when to dereference aliases. Defaults to never
- never dereference aliases (default), always
dereference aliases, only while search ing or only to find
the base object.
- -H ldap_uri
- Specity the LDAP server to connect to by LDAP URI (requires
OpenLDAP libraries). Servers can also be specified last on the command
- -h ldap_server
- Specify the LDAP server to connect to. Servers can also be
specified last on the command line.
- -p ldap_port
- Specify an alternate TCP port where the LDAP server is
listening if other than the default LDAP port 389. Can also be specified
within the server specification by using servername:port syntax.
- -v 2|3
- LDAP protocol version. Defaults to 3 if not
- Use TLS encryption
- -S certpath
- Enable LDAP over SSL (requires Netscape LDAP API
- -c connect_timeout
- Specify timeout used when connecting to LDAP servers
(requires Netscape LDAP API libraries)
- -t search_timeout
- Specify time limit on LDAP search operations
- Debug mode where each step taken will get reported in
detail. Useful for understanding what goes wrong if the results is not
what is expected.
For directories using the RFC2307 layout with a single domain, all you need to
specify is usually the base DN under where your users are located and the
If you have sub-domains then you need to use a search filter approach to locate
your user DNs as these can no longer be constructed directly from the base DN
and login name alone:
basic_ldap_auth -b dc=your,dc=domain -f
And similarly if you only want to allow access to users having a specific
basic_ldap_auth -b dc=your,dc=domain -f
Or if the user attribute of the user DN is cn
instead of uid
you do not want to have to search for the users then you could use something
like the following example for Active Directory:
basic_ldap_auth -u cn -b
If you want to search for the user DN and your directory does not allow
anonymous searches then you must also use the -D
specify a user DN and password to log in as to perform the searches, as in the
following complex Active Directory example
basic_ldap_auth -P -R -b dc=your,dc=domain
-D cn=squid,cn=users,dc=your,dc=domain -w secretsquidpassword -f
When constructing search filters it is strongly recommended to test
the filter using ldapsearch
before you attempt to use
This to verify that the filter matches what you
This program is written by Glenn Newton
<email@example.com> Henrik Nordstrom
This manual is written by Henrik Nordstrom
* Copyright (C) 1996-2016 The Squid Software Foundation and contributors
* Squid software is distributed under GPLv2+ license and includes
* contributions from numerous individuals and organizations.
* Please see the COPYING and CONTRIBUTORS files for details.
This program and documentation is copyright to the authors named above.
Distributed under the GNU General Public License (GNU GPL) version 2 or later
Questions on the usage of this program can be sent to the Squid Users mailing
Or to your favorite LDAP list/friend if the question is more related to LDAP
Bug reports need to be made in English. See
http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need
to include with your bug report.
Report bugs or bug fixes using http://bugs.squid-cache.org/
Report serious security bugs to Squid Bugs
Report ideas for new improvements to the Squid Developers mailing list
Your favorite LDAP documentation.
- The String Representation of LDAP Search Filters,
The Squid FAQ wiki http://wiki.squid-cache.org/SquidFaq
The Squid Configuration Manual http://www.squid-cache.org/Doc/config/