ext_ldap_group_acl(8)

1ext_ldap_group_acl(8)       System Manager's Manual      ext_ldap_group_acl(8)
2
3
4

NAME

6       ext_ldap_group_acl - Squid LDAP external acl group helper
7
8       Version 2.18
9

SYNOPSIS

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

DESCRIPTION

15       ext_ldap_group_acl allows Squid to connect to a LDAP directory  to  au‐
16       thorize  users  via LDAP groups.  LDAP options are specified as parame‐
17       ters on the command line, while the  username(s)  and  group(s)  to  be
18       checked against the LDAP directory are specified on subsequent lines of
19       input to the helper, one username/group pair per line  separated  by  a
20       space.
21
22       As expected by the external_acl_type construct of Squid, after specify‐
23       ing a username and group followed by a new line, this helper will  pro‐
24       duce  either  OK  or ERR on the following line to show if the user is a
25       member of the specified group.
26
27       The program operates by searching with a search  filter  based  on  the
28       users  user name and requested group, and if a match is found it is de‐
29       termined that the user belongs to the group.
30

OPTIONS

32       -a never|always|search|find
33                   When to dereference aliases. Defaults to 'never'
34
35                   never dereference  aliases  (default),  always  dereference
36                   aliases,  only during a search or only to find the base ob‐
37                   ject
38
39       -b basedn   REQUIRED.  Specifies the base DN under which the groups are
40                   located.
41
42       -B basedn   Specifies the base DN under which the users are located (if
43                   different)
44
45       -c connect_timeout
46                   Specify timeout used when connecting to LDAP  servers  (re‐
47                   quires Netscape LDAP API libraries)
48
49       -d          Debug  mode  where each step taken will get reported in de‐
50                   tail.  Useful for understanding what goes wrong if the  re‐
51                   sult is not what was expected.
52
53       -D binddn -w password
54                   The  DN  and password to bind as while performing searches.
55                   Required if the LDAP directory  does  not  allow  anonymous
56                   searches.
57
58                   As  the  password needs to be printed in plain text in your
59                   Squid configuration and will be sent on the command line to
60                   the helper it is strongly recommended to use a account with
61                   minimal associated privileges.  This to limit the damage in
62                   case someone could get hold of a copy of your Squid config‐
63                   uration file or extracts the password used from  a  process
64                   listing.
65
66       -D binddn -W secretfile
67                   The  DN  and  the name of a file containing the password to
68                   bind as while performing searches.
69
70                   Less insecure version of the former parameter pair with two
71                   advantages:  The  password  does  not  occur in the process
72                   listing, and the password is not being compromised if some‐
73                   one  gets  the squid configuration file without getting the
74                   secretfile.
75
76       -E certpath Enable LDAP over SSL (requires Netscape LDAP API libraries)
77
78       -f filter   LDAP search filter used to search the  LDAP  directory  for
79                   any  matching group memberships.   In the filter %u will be
80                   replaced by the user name (or DN if the -F  or  -u  options
81                   are used) and %g by the requested group name.
82
83       -F filter   LDAP  search  filter  used to search the LDAP directory for
84                   any matching users.   In the filter %s will be replaced  by
85                   the user name. If % is to be included literally in the fil‐
86                   ter then use %%
87
88       -g          Specifies that the first query argument sent to the  helper
89                   by Squid is a extension to the basedn and will be temporar‐
90                   ily added in front of the global basedn for this query.
91
92       -h ldapserver
93                   Specify the LDAP server to connect to
94
95       -H ldapuri  Specify the LDAP server to connect to by a  LDAP  URI  (re‐
96                   quires OpenLDAP libraries)
97
98       -K          Strip  Kerberos  Realm  component  from user names (@ sepa‐
99                   rated)
100
101       -p ldapport Specify an alternate TCP port where the LDAP server is lis‐
102                   tening if other than the default LDAP port 389.
103
104       -P          Use a persistent LDAP connection. Normally the LDAP connec‐
105                   tion is only open while verifying a users group  membership
106                   to  preserve  resources  at  the  LDAP  server. This option
107                   causes the LDAP connection to be kept open, allowing it  to
108                   be  reused  for  further  user validations. Recommended for
109                   larger installations.
110
111       -R          Do not follow referrals
112
113       -s base|one|sub
114                   search scope. Defaults to sub
115
116                   base object only,
117
118                   one level below the base object or
119
120                   subtree below the base object
121
122       -S          Strip NT domain name component from user names (/ or \ sep‐
123                   arated)
124
125       -t search_timeout
126                   Specify time limit on LDAP search operations
127
128       -u attr     LDAP  attribute used to construct the user DN from the user
129                   name and base dn without needing to search for the user.  A
130                   maximum of 16 occurrences of %s are supported.
131
132       -v 2|3      LDAP protocol version. Defaults to 3 if not specified.
133
134       -Z          Use TLS encryption
135

CONFIGURATION

137       This  helper  is  intended to be used as an external_acl_type helper in
138       squid.conf .
139              external_acl_type ldap_group %LOGIN  /path/to/ext_ldap_group_acl
140              ...
141              acl group1 external ldap_group Group1
142              acl group2 external ldap_group Group2
143
144       NOTE:  When constructing search filters it is recommended to first test
145       the filter using ldapsearch to verify that the filter matches what  you
146       expect before you attempt to use ext_ldap_group_acl
147

AUTHOR

149       This  program  was  written  by Flavio Pescuma <flavio@marasystems.com>
150       Henrik Nordstrom <hno@squid-cache.org>
151
152       Based on prior  work  in  squid_ldap_auth  by  Glen  Newton  <glen.new‐
153       ton@nrc.ca>
154
155       This manual was written by Henrik Nordstrom <hno@marasystems.com>
156

COPYRIGHT

158        *  Copyright (C) 1996-2023 The Squid Software Foundation and contribu‐
159       tors
160        *
161        * Squid software is distributed under GPLv2+ license and includes
162        * contributions from numerous individuals and organizations.
163        * Please see the COPYING and CONTRIBUTORS files for details.
164
165       This program and documentation is copyright to the authors named above.
166
167       Distributed under the GNU General Public License (GNU GPL) version 2 or
168       later (GPLv2+).
169

QUESTIONS

171       Questions  on  the usage of this program can be sent to the Squid Users
172       mailing list <squid-users@lists.squid-cache.org>
173
174       Or contact your favorite LDAP list/friend if the question is  more  re‐
175       lated to LDAP than Squid.
176

REPORTING BUGS

178       Bug  reports  need  to  be  made  in  English.  See https://wiki.squid-
179       cache.org/SquidFaq/BugReporting for details of what you need to include
180       with your bug report.
181
182       Report bugs or bug fixes using https://bugs.squid-cache.org/
183
184       Report  serious  security  bugs  to Squid Bugs <squid-bugs@lists.squid-
185       cache.org>
186
187       Report ideas for new improvements to the Squid Developers mailing  list
188       <squid-dev@lists.squid-cache.org>
189