squid_ldap_auth(8)                                                                                            squid_ldap_auth(8)



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 authentica-
       tion.  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 pre-
              serve 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 <hnoATsquid-cache.org>

       squid_ldap_auth is written by Glenn Newton <gnewtonATwapiti.ca> and Henrik Nordstrom <hnoATsquid-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-usersATsquid-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-bugsATsquid-cache.org> or ideas for new  improvements  to  Squid  Developers
       <squid-devATsquid-cache.org>

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



Squid LDAP Auth                                          14 January 2005                                      squid_ldap_auth(8)