Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

basic_ldap_auth (8)


basic_ldap_auth - LDAP authentication helper for Squid


basic_ldap_auth  -b "  base  DN  " [-u  attribute  ] [ options ] [ LDAP
server name [: port ]| URI ]...
basic_ldap_auth -b " base DN " -f " LDAP search filter " [ options  ] [
LDAP server name [: port ]| URI ]...


basic_ldap_auth(8)          System Manager's Manual         basic_ldap_auth(8)

       basic_ldap_auth - LDAP authentication helper for Squid

       basic_ldap_auth  -b "  base  DN  " [-u  attribute  ] [ options ] [ LDAP
       server name [: port ]| URI ]...
       basic_ldap_auth -b " base DN " -f " LDAP search filter " [ options  ] [
       LDAP server name [: port ]| URI ]...

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

       -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 "uid=%s" 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 criteria 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 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

       -a never|always|search|find
                   when to dereference aliases. Defaults to never

                   never dereference  aliases  (default),  always  dereference
                   aliases,  only  during  a  search  or only to find the base

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

       -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 lis-
                   tening if other than the default LDAP port 389. Can also be
                   specified  within the server specification by using server-
                   name:port syntax.

       -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)

       -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

       -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-
       cific attribute

              basic_ldap_auth -b  dc=your,dc=domain  -f  (&(uid=%s)(specialat-
              tribute=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:

              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
              (&(userPrincipalName=%s)(objectClass=Person))   activedirectory-

       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  <gnewton@wapiti.cisti.nrc.ca>
       Henrik Nordstrom <hno@squid-cache.org> This manual is written by Henrik
       Nordstrom <hno@squid-cache.org>

        * Copyright (C) 1996-2021 The Squid Software Foundation and  contribu-
        * 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 (GPLv2+).

       Questions on the usage of this program can be sent to the  Squid  Users
       mailing list <squid-users@lists.squid-cache.org>

       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  <squid-bugs@lists.squid-

       Report  ideas for new improvements to the Squid Developers mailing list

       See attributes(7) for descriptions of the following attributes:

       |Availability   | web/proxy/squid  |
       |Stability      | Uncommitted      |

       squid(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/

       Source code for open source software components in Oracle  Solaris  can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source    was    downloaded    from     http://www.squid-cache.org/Ver-

       Further information about this software can be found on the open source
       community website at http://www.squid-cache.org/.

                                14 January 2005             basic_ldap_auth(8)