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,