Provided by: squid-openssl_5.7-1ubuntu3_amd64 bug

NAME

       basic_ldap_auth - LDAP authentication helper for Squid

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

       -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  "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  someone gets the squid configuration file without getting the
                   secretfile.

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

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

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

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

CONFIGURATION

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

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

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

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

AUTHOR

       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

        * Copyright (C) 1996-2022 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 (GPLv2+).

QUESTIONS

       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.

REPORTING BUGS

       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-cache.org>

       Report  ideas  for  new  improvements  to  the  Squid  Developers  mailing  list   <squid-
       dev@lists.squid-cache.org>

SEE ALSO

       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/

                                         14 January 2005                       basic_ldap_auth(8)