squid_ldap_auth - Squid LDAP authentication helper


squid_ldap_auth -b "base DN" [-u attribute] [options] [ldap_server_name[:port]|URI]...
-b "base DN" -f "LDAP search filter" [options] [ldap_server_name[:port]|URI]...


This helper 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 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.
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 "uid=%s" for RFC2037 directories. For a detailed description of LDAP search filter syntax see RFC2254.

-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 searches.

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 searching or only to find the base object

-H ldapuri

Specity the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries). Servers can also be specified last on the command line.

-h ldapserver

Specify the LDAP server to connect to. Servers can also be specified last on the command line.

-p ldapport

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 specificiation by using servername:port syntax.

-v 2|3

LDAP protocol version. Defaults to 3 if not specified.


Use TLS encryption


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


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:

squid_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 direcly from the base DN and login name alone:

squid_ldap_auth -b "dc=your,dc=domain" -f "uid=%s" ldapserver

And similarily if you only want to allow access to users having a specific attribute

squid_ldap_auth -b "dc=your,dc=domain" -f "(&(uid=%s)(specialattribute=value))" ldapserver

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:

squid_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 specify a user DN and password to log in as to perform the searches, as in the following complex Active Directory example

squid_ldap_auth -P -R -b "dc=your,dc=domain" -D "cn=squid,cn=users,dc=your,dc=domain" -w "secretsquidpassword" -f "(&(userPrincipalName=%s)(objectClass=Person))" activedirectoryserver


When constructing search filters it is strongly recommended to test the filter using ldapsearch before you attempt to use squid_ldap_auth. This to verify that the filter matches what you expect.


This manual page was written by Henrik Nordstrom <hno@squid-cache.org>

squid_ldap_auth is written by Glenn Newton <gnewton@wapiti.cisti.nrc.ca> and Henrik Nordstrom <hno@squid-cache.org>


Will crash if other % values than %s is used in -f, or if more than 15 %s is used.


Any questions on usage can be sent to Squid Users <squid-users@squid-cache.org>, or to your favorite LDAP list/friend if the question is more related to LDAP than Squid.


Report bugs or bug-fixes to Squid Bugs <squid-bugs@squid-cache.org> or ideas for new improvements to Squid Developers <squid-dev@squid-cache.org>


Your favorite LDAP documentation
- The String Representation of LDAP Search Filters,


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.