MAN page from OpenSuSE squid-7.5-proxy.2.2.x86_64.rpm

basic_ldap_auth

Section: Maintenance Commands (8)
Updated: 14 January 2005
Index

NAME

basic_ldap_auth - LDAP authentication helper for Squid

SYNOPSIS

basic_ldap_auth-b "base DN" [-uattribute] [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_authallows Squid to connect to a LDAP directory tovalidate 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 theLDAP directory are specified on subsequent lines of input to thehelper, one username/password pair per line separated by a space.

As expected by the basic authentication construct of Squid, afterspecifying a username and password followed by a new line, thishelper will produce eitherOKorERRon the following line to show if the specified credentials are correctaccording to the LDAP directory.

The program has two major modes of operation. In the default modeof operation the users DN is constructed using the base DN anduser attribute. In the other mode of operation a searchfilter 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 filterto locate the user DN. Required if the usersare in a hierarchy below the base DN, or if the login name isnot what builds the user specific part of the users DN.
The search filter can contain up to 15 occurrences of%swhich will be replaced by the username, as in"uid=%s"for RFC2037 directories. For a detailed description of LDAP searchfilter syntax see RFC2254.
Will crash if other%values than%sare used, or if more than 15%sare 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 filteris specified (-foption). Defaults touid
Note:This can only be done if all your users are located directly underthe same position in the LDAP tree and the login name is used for namingeach user object. If your LDAP tree does not match these criteria or ifyou want to filter who are valid users then you need to use a search filterto search for your users DN (-foption).
-U passwordattr: Useldap_compareinstead ofldap_simple_bindto verify the users password.passwordattris the LDAP attribute storing the users password.
-s base|one|sub: Search scope when performing user DN searches specifiedby the-foption. Defaults tosub
: baseobject only,
: onelevel below the base object or
: subtreebelow the base object
-D binddn -w password: The DN and password to bind as while performing searches. Required by the-fflag if the directory does not allow anonymous searches.
As the password needs to be printed in plain text in your Squid configurationit 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 yourSquid configuration file.
-D binddn -W secretfile: The DN and the name of a file containing the passwordto 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 connectionis only open while validating a username to preserve resourcesat the LDAP server. This option causes the LDAP connection tobe kept open, allowing it to be reused for further uservalidations. Recommended for larger installations.
-O: Only bind once per LDAP connection. Some LDAP servers do notallow re-binding as another user after a successfulldap_bind.The use of this option always opens a new connection for eachlogin attempt. If combined with the-Poption for persistentLDAP connection then the connection used for searching for theuser DN is kept persistent but a new connection is openedto verify each users password once the DN is found.
-R: Do not follow referrals
-a never|always|search|find: when to dereference aliases. Defaults tonever
: neverdereference aliases (default),alwaysdereference aliases, only during asearchor only tofindthe 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 laston the command line.
-p ldap_port: Specify an alternate TCP port where the LDAP server is listening ifother than the default LDAP port 389. Can also be specified within theserver specification by using servername:port syntax.
-v 2|3: LDAP protocol version. Defaults to 3if not specified.
-Z: Use TLS encryption
-S certpath: Enable LDAP over SSL (requires Netscape LDAP API libraries)
-c connect_timeout: Specifytimeoutused when connecting to LDAP servers (requiresNetscape 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 isnot what is expected.

CONFIGURATION

For directories using the RFC2307 layout with a single domain, allyou need to specify is usually the base DN under where your usersare 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 approachto locate your user DNs as these can no longer be constructed directlyfrom 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 aspecific attribute

: basic_ldap_auth -b dc=your,dc=domain -f (&(uid=%s)(specialattribute=value)) ldapserver

Or if the user attribute of the user DN iscninstead ofuidand you do not want to have to search for the users then you could use somethinglike 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 allowanonymous searches then you must also use the-Dand-wflags to specify a user DN and password to log in as to perform the searches, as in thefollowing 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 filterusingldapsearchbefore you attempt to usebasic_ldap_auth.This to verify that the filter matches what you expect.

AUTHOR

This program is written by Glenn Newton <gnewtonAATTwapiti.cisti.nrc.ca>Henrik Nordstrom <hnoAATTsquid-cache.org>This manual is written by Henrik Nordstrom <hnoAATTsquid-cache.org>

COPYRIGHT

* Copyright (C) 1996-2026 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 theSquid Users mailing list<squid-usersAATTlists.squid-cache.org>

Or to your favorite LDAP list/friend if the question is more related toLDAP than Squid.

REPORTING BUGS

Bug reports need to be made in English.See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs toSquid Bugs <squid-bugsAATTlists.squid-cache.org>

Report ideas for new improvements to theSquid Developers mailing list<squid-devAATTlists.squid-cache.org>

This document was created byman2html,using the manual pages.