Ubuntu Manpage: basic_ldap_auth - LDAP authentication helper for Squid

name
synopsis
description
options
configuration
author
copyright
questions
reporting bugs
see also

Provided by: squid_3.5.27-1ubuntu1.14_amd64

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-2017 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@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>