basic_ldap_auth(8)basic_ldap_auth(8)NAMEbasic_ldap_auth - LDAP authentication helper for Squid
SYNOPSISbasic_ldap_auth-b base DN attribute ] [ options ] [ LDAP server name
[: port ]| URI ]...
basic_ldap_auth-b base DN LDAP search filter options ] [ LDAP server
name [: port ]| URI ]...
DESCRIPTIONbasic_ldap_auth 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 spec‐
ifying a username and password followed by a new line, this helper will
produce either OK or ERR 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 base DN.
OPTIONS-b basedn REQUIRED. Specifies the base DN under which the users are
-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
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 fil‐
ter 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).
Use ldap_compare instead of ldap_simple_bind to verify the
users password. passwordattr is the LDAP attribute storing
the users password.
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
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 some‐
one gets the squid configuration file without getting the
-P Use a persistent LDAP connection. Normally the LDAP connec‐
tion 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 installa‐
-O 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 con‐
nection 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.
-R Do not follow referrals
when to dereference aliases. Defaults to never
never dereference aliases (default), always dereference
aliases, only while search ing or only to find the base
-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 line.
Specify the LDAP server to connect to. Servers can also be
specified last on the command line.
Specify an alternate TCP port where the LDAP server is lis‐
tening if other than the default LDAP port 389. Can also be
specified within the server specification by using server‐
-v 2|3 LDAP protocol version. Defaults to 3 if not specified.
-Z Use TLS encryption
-S certpath Enable LDAP over SSL (requires Netscape LDAP API libraries)
Specify timeout used when connecting to LDAP servers
(requires Netscape LDAP API libraries)
Specify time limit on LDAP search operations
-d 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 server name:
basic_ldap_auth-b ou=people,dc=your,dc=domain ldapserver
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 uid=%s ldapserver
And similarly if you only want to allow access to users having a spe‐
basic_ldap_auth-b dc=your,dc=domain -f (&(uid=%s)(specialat‐
Or if the user attribute of the user DN is cn instead of uid and 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 cn=Users,dc=your,dc=domain ldapserver
If you want to search for the user DN and your directory does not allow
anonymous searches then you must also use the -D and -w flags to spec‐
ify 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
NOTE: When constructing search filters it is strongly recommended to
test the filter using ldapsearch before you attempt to use
basic_ldap_auth. This to verify that the filter matches what you
This program is written by Glenn Newton <email@example.com>
Henrik Nordstrom <firstname.lastname@example.org> This manual is written by Henrik
This program and documentation is copyright to the authors named above.
Distributed under the GNU General Public License (GNU GPL) version 2 or
Questions on the usage of this program can be sent to the Squid Users
mailing list <email@example.com>
Or to your favorite LDAP list/friend if the question is more related to
LDAP than Squid.
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 <firstname.lastname@example.org>
Report ideas for new improvements to the Squid Developers mailing list
SEE ALSOsquid(8), ldapsearch(1), GPL(7),
Your favorite LDAP documentation.
RFC2254 - 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/
14 January 2005 basic_ldap_auth(8)