squid_ldap_auth(8)					      System Manager's Manual						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 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  speci-
       fied 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 directo-
	      ries. 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 mini-
	      mal 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. Recom-
	      mended 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  pass-
	      word 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 2 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 "(&(userPrincipal-
	      Name=%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,

Squid LDAP Auth 						  14 January 2005						squid_ldap_auth(8)