Provided by: squid3_3.1.19-1ubuntu2_amd64 bug

NAME

       squid_ldap_auth - Squid LDAP authentication helper

SYNOPSIS

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

DESCRIPTION

       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.

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

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

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

       -Z     Use TLS encryption

       -Scertpath
              Enable LDAP over SSL (requires Netscape LDAP API libraries)

       -cconnect_timeout
              Specify timeout used when connecting to LDAP servers (requires  Netscape  LDAP  API
              libraries)

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

EXAMPLES

       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

NOTES

       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.

AUTHOR

       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>

KNOWN ISSUES

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

QUESTIONS

       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.

REPORTING BUGS

       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>

SEE ALSO

       ldapsearch(1),
       Your favorite LDAP documentation
       RFC2254 - The String Representation of LDAP Search Filters,