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

NAME

       basic_ldap_auth - LDAP authentication helper for Squid

SYNOPSIS

       basic_ldap_auth -b  base DN attribute ] [ options ] [ LDAP server name [: port ]| URI ]...
       basic_ldap_auth -b  base DN 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   for  RFC2037  directo-
		   ries. 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 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  valida-
		   tions. 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 search ing or only to find the base object.

       -H ldap_uri Specity 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 some-
       thing 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 (&(userPrincipal-
	      Name=%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 Hen-
       rik Nordstrom <hno@squid-cache.org>

COPYRIGHT

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

       Report ideas for new improvements to the Squid Developers mailing list <squid-dev@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)