basic_ldap_auth(8)

📦
version 7.7 · 7 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 basic_ldap_auth(8) — LDAP authentication helper for Squid 💖

okay bestie, sit down, hydrate, because we're about to make LDAP auth make sense. this is basic_ldap_auth, a lil helper from the System Manager's Manual section (section 8, system admin tools, iykyk). she's not glamorous but she WORKS and she's lowkey carrying your whole proxy login situation. 🫶

✨ 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 ✨

so. basic_ldap_auth lets Squid go talk to an LDAP directory and check whether a username + password pair is actually legit, for Basic HTTP authentication. the way it works: you hand all your LDAP settings over as command-line parameters, and then the username(s) and password(s) you want checked get fed in on subsequent lines of input to the helper — one username/password pair per line, separated by a single space. no cap. 💅

and because Squid's basic auth construct expects a very specific lil ritual: after you give it a username and password and a newline, this helper will print either OK or ERR on the following line, telling you whether those credentials check out according to the LDAP directory. that's it. that's the whole vibe check. ✅❌

the program has two major modes of operation:

  1. default mode — the user's DN is constructed from the base DN plus the user attribute.
  2. the other mode — a search filter is used to locate valid user DNs down below the base DN.

pick your fighter. both slay. 💖

✨ OPTIONS ✨

  • -b basedn — REQUIRED. this is the base DN under which your users are located. no base DN, no party. 🚫
  • -f filter — the LDAP search filter used to locate the user DN. you need this if your users live in a hierarchy below the base DN, or if the login name isn't the thing that builds the user-specific part of the user's DN. the search filter can contain up to 15 occurrences of %s, which get replaced by the username — like uid=%s for RFC2037 directories. for the full deets on LDAP search filter syntax, go read RFC2254. 📚
💀 Will crash if other % values than %s are used, or if more than 15 %s are used. not a drill, bestie. she will simply pass away.
  • -u userattr — the name of the DN attribute that holds the username/login. combined with the base DN to construct the user's DN when no search filter is specified (that's the -f option). defaults to uid. 🎀 Note: this can only be done if all your users sit directly under the same position in the LDAP tree, and the login name is what names each user object. if your LDAP tree doesn't match those criteria, or if you want to filter who counts as a valid user, then you need to use a search filter to find your users' DN — that's the -f option, babes.
  • -U passwordattr — use ldap_compare instead of ldap_simple_bind to verify the user's password. passwordattr is the LDAP attribute storing the user's password. 🔐
  • -s base|one|sub — the search scope used when performing user DN searches specified by the -f option. defaults to sub.
    • base — object only,
    • one — one level below the base object, or
    • sub — 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.
⚠️ since the password has to be printed in plain text in your Squid configuration, it is strongly recommended to use an account with minimal associated privileges. this limits the damage in case someone gets hold of a copy of your Squid configuration file. protect yourself, queen. 👑
  • -D binddn -W secretfile — the DN, plus the name of a file containing the password to bind as while performing searches. this is the less insecure version of the former parameter pair, with two advantages: the password does not occur in the process listing, and the password isn't compromised if someone gets the squid configuration file without getting the secretfile. glow up. ✨
  • -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 keeps the LDAP connection open so it can 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. using this option always opens a new connection for each login attempt. if combined with the -P option for a 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 user's password once the DN is found. 🔄
  • -R — do not follow referrals. 🚫🧭
  • -a never|always|search|find — when to dereference aliases. defaults to never.
    • never — never dereference aliases (default),
    • always — always dereference aliases,
    • search — only during a search, or
    • find — 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 gets reported in detail. super useful for understanding what goes wrong if the result isn't what you expected. 🐛🔎

✨ CONFIGURATION ✨

for directories using the RFC2307 layout with a single domain, usually all you need to specify is the base DN under where your users are located, plus the server name:

basic_ldap_auth -b ou=people,dc=your,dc=domain ldapserver

if you've got sub-domains, then you need the search filter approach to locate your user DNs, because they 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, 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, so the searches can be performed — 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 verifies that the filter matches what you expect. test first, ship later. 🧪

✨ AUTHOR ✨

this program is written by Glenn Newton <gnewton@wapiti.cisti.nrc.ca> and Henrik Nordstrom <hno@squid-cache.org>. this manual is written by Henrik Nordstrom <hno@squid-cache.org>. legends, honestly. 👑👑

 * 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 ✨

got questions about using this program? send them to the Squid Users mailing list <squid-users@lists.squid-cache.org> 💌

or hit up your favorite LDAP list/friend if the question is more about LDAP than Squid. mutuals helping mutuals. 🫂

✨ 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 to Squid Bugs <squid-bugs@lists.squid-cache.org> 🚨

report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org> 💡

✨ SEE ALSO ✨

okay and that's the whole page!! 🌈 this one's dated 14 January 2005 and it lives in section basic_ldap_auth(8) — oldie but a goodie, still eating after all these years. go configure something iconic bestie 💅🎀✨

📦 where this page comes from