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

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

8. Notes

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

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