1.if !'po4a'hide' .TH ext_ad_group_acl.exe 8
2.
3.SH NAME
4ext_ad_group_acl.exe \- Squid external ACL helper to check Windows users group membership.
5.PP
6Version 2.0
7.
8.SH SYNOPSIS
9.if !'po4a'hide' .B ext_ad_group_acl.exe
10.if !'po4a'hide' .B "[\-D "
11domain
12.if !'po4a'hide' .B "] [\-cdGh]"
13.
14.SH DESCRIPTION
15.B ext_ad_group_acl.exe
16is an installed binary in Squid for Windows builds.
17.PP
18This helper must be used in with an authentication scheme (typically
19Basic, NTLM or Negotiate) based on Windows Active Directory domain users.
20.PP
21It reads from the standard input the domain username and a list of groups
22and tries to match each against the groups membership of the specified
23username.
24.PP
25Two running mode are available:
26.if !'po4a'hide' .TP 12
27.B "\- Local mode:"
28membership is checked against machine's local groups, cannot be used when
29running on a Domain Controller.
30.PP
31.if !'po4a'hide' .TP 12
32.B "\- Active Directory Global mode:"
33membership is checked against the whole Active Directory Forest of the
34machine where Squid is running.
35.PP
36The minimal Windows version needed to run
37.B ext_ad_group_acl.exe
38is a Windows 2000 SP4 member of an Active Directory Domain.
39.PP
40When running in Active Directory Global mode, all types of Active Directory
41security groups are supported:
42.B "Domain Global"
43,
44.B "Domain Local"
45from user's domain,
46.B "Universal"
47and Active Directory group nesting is fully supported.
48.
49.SH OPTIONS
50.if !'po4a'hide' .TP 12
51.if !'po4a'hide' .B "\-c"
52Use case insensitive compare (local mode only).
53.
54.if !'po4a'hide' .TP
55.if !'po4a'hide' .B "\-d"
56Write debug info to stderr.
57.
58.if !'po4a'hide' .TP
59.if !'po4a'hide' .B "\-D" domain
60Specify the default user's
61.B domain
62.
63.if !'po4a'hide' .TP
64.if !'po4a'hide' .B "\-G"
65Start helper in Active Directory Global mode.
66.
67.if !'po4a'hide' .TP
68.if !'po4a'hide' .B "\-h"
69Display the binary help and command line syntax info using stderr.
70.
71.SH CONFIGURATION
72.PP
73When running in Active Directory Global mode, the AD Group can be specified using the
74following syntax:
75.
76.if !'po4a'hide' .TP 5
77.B "1." Plain NT4 Group Name
78.
79.if !'po4a'hide' .TP
80.B "2." Full NT4 Group Name
81.
82.if !'po4a'hide' .TP
83.B "3." Active Directory Canonical name
84.
85.PP
86As Exampled:
87.if !'po4a'hide' .TP 5
88.if !'po4a'hide' .B "1." Proxy-Users
89.
90.if !'po4a'hide' .TP
91.if !'po4a'hide' .B "2." MYDOMAIN\Proxy-Users
92.
93.if !'po4a'hide' .TP
94.if !'po4a'hide' .B "3." mydomain.local/Groups/Proxy-Users
95.PP
96When using Plain NT4 Group Name, the Group is searched in the user's domain.
97.if !'po4a'hide' .RS
98.if !'po4a'hide' .B external_acl_type AD_global_group %LOGIN c:/squid/libexec/ext_ad_group_acl.exe -G
99.if !'po4a'hide' .br
100.if !'po4a'hide' .B external_acl_type NT_local_group %LOGIN c:/squid/libexec/ext_ad_group_acl.exe
101.if !'po4a'hide' .br
102.if !'po4a'hide' .br
103.if !'po4a'hide' .B "acl GProxyUsers external AD_global_group MYDOMAIN\GProxyUsers"
104.if !'po4a'hide' .br
105.if !'po4a'hide' .B acl LProxyUsers external NT_local_group LProxyUsers
106.if !'po4a'hide' .br
107.if !'po4a'hide' .B acl password proxy_auth REQUIRED
108.if !'po4a'hide' .br
109.if !'po4a'hide' .br
110.if !'po4a'hide' .B http_access allow password GProxyUsers
111.if !'po4a'hide' .br
112.if !'po4a'hide' .B http_access allow password LProxyUsers
113.if !'po4a'hide' .br
114.if !'po4a'hide' .B http_access deny all
115.if !'po4a'hide' .RE
116.
117.PP
118In the previous example all validated AD users member of
119.I "MYDOMAIN\GProxyUsers"
120domain group or member of
121.I LProxyUsers
122machine local group are allowed to
123use the cache.
124.PP
125Groups with spaces in name, for example
126.B "Domain Users"
127, must be quoted and the acl data (
128.B "Domain Users"
129) must be placed into a separate file included
130by specifying
131.B "/path/to/file" .
132The previous example will be:
133.if !'po4a'hide' .RS
134.if !'po4a'hide' acl ProxyUsers external NT_global_group \"c:/squid/etc/DomainUsers\"
135.if !'po4a'hide' .RE
136and the DomainUsers files will contain only the following line:
137.if !'po4a'hide' .RS
138"Domain Users"
139.if !'po4a'hide' .RE
140.
141.PP
142.B NOTE 1:
143When running in Active Directory Global mode, for better performance,
144all Domain Controllers of the Active Directory forest should be configured
145as Global Catalog.
146.
147.PP
148.B NOTE 2:
149When running in local mode, the standard group name comparison is case
150sensitive, so group name must be specified with same case as in the
151local SAM database.
152.
153It is possible to enable case insensitive group name comparison (
154.B \-c
155),
156but on some non\-English locales, the results can be unexpected.
157.
158.PP
159.B NOTE 3:
160Native WIN32 NTLM and Basic helpers must be used without the
161.B \-A
162and
163.B \-D
164switches.
165.
166.PP
167Refer to Squid documentation for more details on
168.B squid.conf
169.
170.SH TESTING
171.PP
172I strongly recommend that
173.B ext_ad_group_acl.exe
174is tested prior to being used in a
175production environment. It may behave differently on different platforms.
176.
177.PP
178To test it, run it from the command line. Enter username and group
179pairs separated by a space (username must entered with URL-encoded
180.I domain%5Cusername
181syntax). Press
182.B ENTER
183to get an
184.B OK
185or
186.B ERR
187message.
188.PP
189Make sure pressing
190.B CTRL+D
191behaves the same as a carriage return.
192.PP
193Make sure pressing
194.B CTRL+C
195aborts the program.
196.
197.PP
198Test that entering no details does not result in an
199.B OK
200or
201.B ERR
202message.
203.PP
204Make sure pressing
205.B CTRL+D
206behaves the same as a carriage return.
207.PP
208Make sure pressing
209.B CTRL+C
210aborts the program.
211.
212.PP
213Test that entering no details does not result in an
214.B OK
215or
216.B ERR
217message.
218.PP
219Test that entering an invalid username and group results in an
220.B ERR
221message.
222.PP
223Test that entering an valid username and group results in an
224.B OK
225message.
226.
227.SH AUTHOR
228This program was written by
229.if !'po4a'hide' .I Guido Serassio <guido.serassio@acmeconsulting.it>
230.PP
231Based on prior work in
232.B "mswin_check_lm_group (ext_lm_group_acl)"
233.PP
234This manual was written by
235.if !'po4a'hide' .I Guido Serassio <guido.serassio@acmeconsulting.it>
236.if !'po4a'hide' .I Amos Jeffries <amosjeffries@squid-cache.org>
237.
238.SH COPYRIGHT
239.PP
240 * Copyright (C) 1996-2021 The Squid Software Foundation and contributors
241 *
242 * Squid software is distributed under GPLv2+ license and includes
243 * contributions from numerous individuals and organizations.
244 * Please see the COPYING and CONTRIBUTORS files for details.
245.PP
246This program and documentation is copyright to the authors named above.
247.PP
248Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
249.
250.SH QUESTIONS
251Questions on the usage of this program can be sent to the
252.I Squid Users mailing list
253.if !'po4a'hide' <squid-users@lists.squid-cache.org>
254.
255.SH REPORTING BUGS
256Bug reports need to be made in English.
257See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
258.PP
259Report bugs or bug fixes using http://bugs.squid-cache.org/
260.PP
261Report serious security bugs to
262.I Squid Bugs <squid-bugs@lists.squid-cache.org>
263.PP
264Report ideas for new improvements to the
265.I Squid Developers mailing list
266.if !'po4a'hide' <squid-dev@lists.squid-cache.org>
267.
268.SH SEE ALSO
269.if !'po4a'hide' .BR squid "(8), "
270.if !'po4a'hide' .BR GPL "(7), "
271.br
272The Squid FAQ wiki
273.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
274.br
275The Squid Configuration Manual
276.if !'po4a'hide' http://www.squid-cache.org/Doc/config/
277