squid_ldap_auth(8)squid_ldap_auth(8)NAMEsquid_ldap_auth - Squid LDAP authentication helper
SYNOPSISsquid_ldap_auth-b "base DN" [-u attribute] [options]
[ldap_server_name[:port]]...]
squid_ldap_auth-b "base DN" -f "LDAP search filter"
[options] [ldap_server_name[:port]...]
DESCRIPTION
This helper allows Squid to connect to a LDAP directory to
validate the user name and password of Basic HTTP authen-
tication.
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 con-
tains 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).
-s base|one|sub
search scope when performing user DN searches spec-
ified 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 recom-
mended to use a account with minimal associated
privileges. This to limit the damage in case some-
one could get hold of a copy of your Squid configu-
ration file.
-D binddn -W secretfile
The DN and the name of a file containing the pass-
word 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.
-R do not follow referrals
-a never|always|search|find
when to dereference aliases. Defaults to 'never'
never dereference aliases (default), always deref-
erence 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)
-h ldapserver
Specify the LDAP server to connect to
-p ldapport
Specify an alternate TCP port where the ldap server
is listening if other than the default LDAP port
389.
-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
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 fil-
ter 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 secretsquid-
password -f (&(userPrincipalName=%s)(object-
Class=Person)) activedirectoryserver
NOTES
When constructing search filters it is strongly recom-
mended 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 <gnew-
ton@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 Develop-
ers <squid-dev@squid-cache.org>
SEE ALSOldapsearch(1),
Your favorite LDAP documentation
RFC2254 - The String Representation of LDAP Search Fil-
ters,
Squid LDAP Auth 1 Mars 2003 squid_ldap_auth(8)
