ext_ldap_group_acl(8)

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

✨ ext_ldap_group_acl — the Squid LDAP external acl group helper ✨

okay bestie, gather round, because this one is the glow-up your Squid proxy needs when it wants to do LDAP group auth 💅 it's a page from the System Manager's Manual, and it's living at Version 2.18 — iconic, no notes.

🦋 SYNOPSIS 🦋

ext_ldap_group_acl -b base-DN -f filter [ options ] [ server [ ':' port ] | URI ] ...

🌸 DESCRIPTION 🌸

so ext_ldap_group_acl is literally the thing that lets Squid slide into an LDAP directory and authorize users by LDAP groups. the LDAP options? those go on the command line as parameters. the username(s) and group(s) you wanna check against the directory? those show up on the following lines of input to the helper — one username/group pair per line, separated by a space. periodt. 🎀

and because Squid's external_acl_type construct expects it, once you hand it a username and a group plus a newline, this helper will spit out either OK or ERR on the next line, showing whether the user is a member of that group. main character energy fr fr ✨

how does it actually work? it runs a search with a search filter based on the user's user name and the requested group, and if it finds a match, boom — the user is in the group. that's it, that's the vibe. 🫶

💖 OPTIONS 💖

  • -a never|always|search|find — when to dereference aliases. defaults to never.
    • never dereference aliases (the default)
    • always dereference aliases
    • only during a search
    • or only to find the base object
  • -b basedn — REQUIRED. specifies the base DN under which the groups are located. no skipping this one bestie, it's mandatory 😤
  • -B basedn — specifies the base DN under which the users are located (if that's different from the groups one).
  • -c connect_timeout — specify the timeout used when connecting to LDAP servers. ⚠️ requires Netscape LDAP API libraries.
  • -d — debug mode, where every single step taken gets reported in detail. lowkey the bestie you want when the result is not what you expected — it tells you exactly what went wrong. 🔍
  • -D binddn -w password — the DN and password to bind as while performing searches. required if the LDAP directory does not allow anonymous searches.
okay so listen: the password has to be printed in plain text in your Squid configuration, and it will be sent on the command line to the helper. so it is strongly recommended to use an account with minimal associated privileges. this limits the damage in case someone could get hold of a copy of your Squid configuration file, or extracts the password used from a process listing. protect yourself, bestie 🚨
  • -D binddn -W secretfile — the DN and 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 is not compromised if someone gets the squid configuration file without getting the secretfile. ate 💅
  • -E certpath — enable LDAP over SSL. ⚠️ requires Netscape LDAP API libraries.
  • -f filter — the LDAP search filter used to search the LDAP directory for any matching group memberships. in the filter, %u will be replaced by the user name (or DN if the -F or -u options are used) and %g by the requested group name.
  • -F filter — the LDAP search filter used to search the LDAP directory for any matching users. in the filter, %s will be replaced by the user name. if % is to be included literally in the filter, then use %%.
  • -g — specifies that the first query argument sent to the helper by Squid is an extension to the basedn, and it will be temporarily added in front of the global basedn for this query.
  • -h ldapserver — specify the LDAP server to connect to.
  • -H ldapuri — specify the LDAP server to connect to by a LDAP URI. ⚠️ requires OpenLDAP libraries.
  • -K — strip Kerberos Realm component from user names (@ separated).
  • -p ldapport — specify an alternate TCP port where the LDAP server is listening, if it's other than the default LDAP port 389.
  • -P — use a persistent LDAP connection. normally the LDAP connection is only open while verifying a user's group membership, to preserve resources at the LDAP server. this option causes the LDAP connection to be kept open, letting it be reused for further user validations. recommended for larger installations. 🏢
  • -R — do not follow referrals.
  • -s base|one|sub — search scope. defaults to sub.
    • base — object only
    • one — one level below the base object
    • sub — subtree below the base object
  • -S — strip NT domain name component from user names (/ or \ separated).
  • -t search_timeout — specify a time limit on LDAP search operations.
  • -u attr — LDAP attribute used to construct the user DN from the user name and base dn, without needing to search for the user. a maximum of 16 occurrences of %s are supported.
  • -v 2|3 — LDAP protocol version. defaults to 3 if not specified.
  • -Z — use TLS encryption. 🔐

🌈 CONFIGURATION 🌈

this helper is intended to be used as an external_acl_type helper in squid.conf.

external_acl_type ldap_group %LOGIN /path/to/ext_ldap_group_acl
...
acl group1 external ldap_group Group1
acl group2 external ldap_group Group2
NOTE: when constructing search filters, it is recommended to first test the filter using ldapsearch to verify that the filter matches what you expect, before you attempt to use ext_ldap_group_acl. test first, ship second, always 🧚

👑 AUTHOR 👑

this program was written by Flavio Pescuma <flavio@marasystems.com> and Henrik Nordstrom <hno@squid-cache.org>.

based on prior work in squid_ldap_auth by Glen Newton <glen.newton@nrc.ca>.

this manual was written by Henrik Nordstrom <hno@marasystems.com>.

 * 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 the Squid Users mailing list <squid-users@lists.squid-cache.org>.

or contact your favorite LDAP list/friend if the question is more related to LDAP than Squid. iykyk 🫶

🔥 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 ⭐

and that's the whole thing bestie 💖 this page is dated 30 January 2005, and it comes to you from the System Manager's Manual (that's the source/version situation for ext_ldap_group_acl(8), version 2.18). now go auth some groups, you've got this 🌟

📦 where this page comes from