Squid ACL Proxy Authentication with External Programs

Last update: 2003/04/14 13:37h CEST

NEW: as of July 1st, 2001 you can hire me for Squid related consultancy via my company Madison Gurkha.

The proxy_auth code has been improved in Squid 2.X, please refer to the comments in the Squid 2.X squid.conf file for instructions on how to use it. These pages are currently a little out-of-date.

1. Introduction
2. Syntax
3. Authentication programs
4. ncsa_auth
5. Patches for various Squid versions
6. Contributed authentication programs
7. Todo
8. Notes
9. Thanks to...

1. Introduction

This ACL Proxy Authentication with External Programs patch implements proxy authentication as a normal ACL and with external authentication programs which are allowed to block. It is a generalization of my earlier patches which were based on the original proxy_auth code provided by Jon Thackray <jrmt@uk.gdscorp.com>.

With the patch applied you can do things like:

authenticate_program /usr/local/squid/bin/ncsa_auth
authenticate_options /usr/local/squid/etc/passwd
authenticate_children 5

acl our_lan src x.x.x.x/24
acl isp_dialin_pool src x.x.x.x/24
acl passwd proxy_auth

http_access allow our_lan
http_access allow isp_dialin_pool passwd
http_access deny  all

This gives proxy access to people from our_lan without a password and also from an ISP's dialin pool if a username/password combination is used. All others are denied.

Other example:

acl password proxy_auth
acl netherlands dstdomain nl
http_access allow netherlands
http_access allow password
http_access deny  all

Pages within the *.nl domain can be reached without authentication, all other pages require a valid username/password combination.

2. Syntax

	acl aclname proxy_auth [ timeout ]

timeout is the optional timeout for username/password caching (default = 3600 secs). A correct username/password is cached by Squid until reconfigure, shutdown (of course :-), a failed proxy authentication or the timeout period.

	authenticate_program program_name
	authenticate_options program_options
	authenticate_children number

program_name should be an authentication program. It can be given up to 32 program_options. number is the number of authentication processes to run (maximum is 32).

To tune the number of authenticate_children, use the cachemgr.cgi CGI script and see how many authentication processes get used. If all get used, increase authenticate_children until you have some unused authentication processes.

3. Authentication programs

An authentication program must read a line on STDIN and then write a line on STDOUT in an endless loop. In case EOF is detected on STDIN it should exit.

On STDIN it receives lines containing

	username cleartextpassword

username must be non-empty and contain no spaces. The username is followed by exactly one space character. The space character is followed by cleartextpassword which is the password in clear text (not encrypted) and which can be empty.

On STDOUT it must output lines which start with one of these keywords:

	OK
	ERR

OK should be given in case the username/password combination was correct. ERR should be give in case the username/password combination was incorrect or when the correctness could not be determined (due to, e.g., a timeout).

Note: make sure the program flushes STDOUT after every write! In Perl this can be accomplished by using '$| = 1;' at the start of the program.

4. ncsa_auth

One authentication program, ncsa_auth, is provided which gives the original proxy authentication support based on NCSA style password files. Usage:

	ncsa_auth passwd_file

passwd_file is an NCSA/Apache-style file of passwords for authenticated proxy access. Each line contains a user:password combination, with the password being standard crypt() format. It should be readable by the userid the ncsa_auth program is running as.

To use it from Squid add

    authenticate_program /usr/local/squid/bin/ncsa_auth
    authenticate_options /usr/local/squid/etc/passwd
    authenticate_children 5

to squid.conf and some appropriate acl and http_access rules.

Note: newer versions of ncsa_auth support password files with comment lines (starting with '#'), empty or blank lines, and extra fields after the usercode and password fields separated by colons (':', i.e. a normal Unix password file).

5. Patches for various Squid versions

The patch is available for the following versions of Squid. For more details about the different versions of the patches and the fixes they contain, read the ChangeLog file. If the patch is not yet available for a newer version of Squid, please try the most recent patch first. Patches are in unified diff format so use a recent version of patch.

Apply the patch in the following way:

	tar zxf squid-1.2.XX-src.tar.gz
	cd squid-1.2.XX
	patch -p1 -l < /tmp/patchfile

If any *.rej files show up, try to merge the changes described in those files manually.

If you apply the patch to an already unpacked and compiled source tree, please run the 'configure' script again.

Available versions:

Patch for 1.1.20 (19980607, contains bugfix for Squid crashes due to invalid Proxy-Authorization headers).
colon.patch contains the bugfix for invalid Proxy-Authorization headers.
Experimental patch for 1.2.beta22 (19980616, ported from 1.1.20, no new things yet, not much tested, no updated docs, etc.).
Experimental patch for 1.2.beta23 (19980726, ported from 1.2.beta22 patch).
Patch for 1.2.beta23pl3 (19980802, updated since 19980730). Contains a few bugfixes, general cleanup, improved ncsa_auth program. This is the candidate for official inclusion into Squid 1.2beta. For convenience, proxy_auth.0730-0802 contains only the changes between the 19980730 and 19980802 versions.

6. Contributed authentication programs

This is a list of authentication programs which can be used with this patch. Please direct questions to the original authors.

If you wrote an authentication program usable with this proxy_auth patch yourself, please send me the URL and I'll add it to the list. If you do not have a place to publish it, I can store it for you in my contrib directory.

LDAP authentication: An LDAP based authentication program by Felix Meschberger (homepage).
LDAP authentication: Another LDAP based authentication program by Alan Sparks.
SMB authentication: SMB based authentication by Richard Huveneers.
mysql_auth.c: MySQL based authentication by Frank Liu. Code last updated September 26, 1999.
PAM based authenticator: PAM based authenticator by Henrik Nordström.
socks5.passwd based authentication: socks5.passwd based authenticator by Everton da Silva Marques.
Radius authenticator: Radius based authenticator in Perl by Edmar Lourenço Borges.

7. Todo

Integrate this patch into Squid 1.2beta before it gets released (started working on it June 14th, 1998). On July 31st, 1998, Duane Wessels told squid-users that he would start adding my patch. So expect it in Squid 1.2beta24.
Store verified passwords encrypted in the username/password cache; a core dump could reveal all passwords (it's recommended to run Squid on a system where no login users are allowed).
Check whether it's possible to let authentication programs return error strings after ERR which can then be given to the user.
Make more authenticator programs like radius_auth, pam_auth, etc. Volunteers welcome :-).

Integrate redirect.c and authenticate.c which are very similar. In fact, authenticate.c was created by applying the following sed command to redirect.c

    sed \
    -e 's/redirector/authenticator/g' \
    -e 's/Redirector/Authenticator/g' \
    -e 's/REDIRECT/AUTHENTICATE/g' \
    -e 's/Redirect/Authenticate/g' \
    -e 's/redirect/authenticate/g'

and some extra code.

Make the authenticator program return an ACL to use (suggested by Anthony Baxter).

8. Notes

In case a note is only relevant to Squid 1.1 or 1.2 this is mentioned.

When using a proxy_auth ACL in an ACL list, make sure it is the last one in the list and the only proxy_auth type ACL in the list:
```
	http_access allow my_users special_sites passwords
    
```
When a Proxy-Authentication header is sent by the browser but it is not needed during ACL checking, the username is NOT logged in access.log.
[Squid 1.1.*] When using proxy_auth acls together with other acls which also need external help (like srcdomain acls which need dnsserver) Squid may get a fatal trap on 'wrong authenticate_state'. This has been fixed in the Squid 1.2 version and is unlikely to be backported in the Squid 1.1 version because of the differences in the code.
[Squid 1.1.*] proxy_auth support is not compiled into Squid by default. To use this feature you must enable the USE_PROXY_AUTH option near the top of src/Makefile. I believe we can remove the #ifdef's when this patch gets integrated into the official Squid release because proxy authentication can now be turned off by not using proxy_auth type ACL's.
[Squid 1.1.*] A good setting for debug_options is "ALL,1 28,9 33,5 44,5" when you are testing this patch.

9. Thanks to...

Thanks to the following people for suggestions, patches and/or remarks:

Chris Pascoe
David Richards
Chris Tilbury
David Luyer
Heiko Schlitterman
Lars Oeschey
Felix Meschberger
Alan Sparks
Bruno Pennec
Richard Huveneers

Last modified: 2003/04/14 13:37h CEST, Arjan de Vet, Arjan.deVet@adv.iae.nl