Linux DevCenter    
 Published on Linux DevCenter (
 See this if you're having trouble printing code examples

Authentication and Squid

by Jennifer Vesperman

About HTTP authentication

HTTP authentication uses the same basic protocols for HTTP web servers and HTTP proxy servers. These protocols have two authentication modes: basic and digest mode. In basic mode, the client passes the user name and the password to the server as a single base64-encoded block. In digest mode, the server encodes the password with a different key in a unidirectional function and the client decodes the function using the password, then returns the key. This proves that the client knows the password, without actually transmitting the password at any point.

To the server (web or proxy), HTTP authentication is stateless. To most clients, it is not -- within a given session, most clients retain user name/password pairs for host names and paths (more accurately, for HTTP realms) that have previously requested authentication.

If the client already has a user name/password pair for a URL, it sends them the page request. If the client does not send the authentication data with a request for a page that requires authentication, the server sends an authentication challenge before sending the page. The client receives the challenge and asks the user for the user name/password pair to send.

The usual method for preventing another user with the same client from using your user name and password is to close the client. This ends the session, and most clients then discard existing user name/password pairs.

Some browsers are persistent and exist for the duration of the desktop being active. Some versions of these will discard user name/password pairs when the HTTP browser is closed, but some versions appear not to.

Because the protocol is stateless for the server, the server cannot (within the protocol) block authentication from multiple clients using the same user name, or log a user out. Patches to server software can be written to force logout-like behavior in a client, or to block multiple clients based on IP addresses, but these are not supported by the protocol and may be ineffective or risky.

Squid has a configuration option (authenticate_ip_ttl) to make authentication "sticky" to the IP address for a period of time. The default is 0 seconds, which is not sticky and therefore correct to the protocol.

Proxy authentication

Related articles:

Using Squid on Intermittent Connections

Installing and Configuring Squid

Comment on this articleShare your experiences using ACLs in Squid.
Post your comments

Proxy server authentication uses the same protocols and techniques as web server authentication, but sends a challenge with the proxy-authenticate field rather than the www-authenticate field. Digest mode is written into the protocol, but proxy authentication is currently unsupported in many browsers and most HTTP proxy and cache servers.

In a chain of proxies, proxy authentication is consumed by the proxy closest to the client which requires authentication, and the authentication information is then not passed to parent proxies. Note that proxies that do not require authentication are not guaranteed to pass proxy authentication further up the chain.

User to proxy authentication

Squid user authentication is set up in $SQUID-HOME/etc/squid.conf. The sections that must be configured are:

You must also compile and install your authentication module.

The realm

The realm is configured with the line proxy_auth_realm.

The user sees the realm in the user name/password request dialog. The default is Squid proxy-caching web server, but you may want to change it from the default as user authentication is done against the realm.

# realm example
proxy_auth_realm Squid proxy-caching web server

The access control list

To tell Squid to check for user authentication, you need to add two special access control lines. The lines are:

acl name proxy_auth REQUIRED
http_access allow name

These lines are inverse to the normal ACL logic. Normally, these lines would permit access to all people who passed the proxy authentication -- however, they actually deny it to anyone who fails authentication. For this reason, the following format is recommended for access control lists that require user authentication:

# set up the acl name for the local network
acl localnetwork proxy_auth
# set up the acl name for user authentication
acl localusers proxy_auth REQUIRED

# set up all the denies for those not in the local network
http_access deny !localnetwork
# set up the user authentication
http_access allow localusers
# set up the allows for the local network
http_access allow localnetwork
# deny anything that passes beyond this point
http_access deny all

Related Reading

Web CachingWeb Caching
By Duane Wessels
Table of Contents
Sample Chapter
Full Description
Read Online -- Safari

This ensures that anyone who is going to be denied because they're outside the local network is denied straight away, rather than passed through to the user authentication process. It's very confusing for the user to be asked for a user name and password and denied even if they enter a valid pair.

Those who fail user authentication are denied at the http_access allow localusers rule, but those who pass authentication are passed on to the next line. This is the explicit allow rule for the local network. If it was not there, the users would fail at the http_access deny all rule.

Squid ACLs have an implicit final rule which reverses the preceding rule. If the last rule was http_access allow localusers, the implicit final rule would be http_access deny all. Authenticated users would be passed through to the deny all, and would be denied access. This is a common misconfiguration.

Incorrect ACL formats

The following format would fail because any user on the local network would be allowed access to the proxy. Authentication would not be checked.

# set up the allows for the local network
http_access allow localnetwork
# set up the user authentication
http_access allow localusers

The following format would fail because the user authentication would succeed, then the check would pass through to the deny all. User authentication allow <whatever> rules act as if they were deny !<whatever>.

# set up the user authentication
http_access allow localusers
# deny anything that passes beyond this point
http_access deny all

The authentication modules

The authentication module is configured with the option authenticate_program authentication module authentication file.

# authenticate_program example
authenticate_program /squid/bin/ncsa_auth /squid/etc/passwd

The standard authentication modules are in $SQUID-HOME/$SQUID-VERSION/auth_modules/. To compile and install the modules, go to their subdirectory and run make, then make install.


auth_modules% cd NCSA
NCSA% make
NCSA% make install

Standard authentication modules

Authenticates against LDAP databases. This needs open LDAP libraries from See the ReadMe file in the LDAP module directory.

Microsoft NT domain authentication. This needs configuration changes made to the source. See the ReadMe file in the MSNT module directory.

Authenticates against the same type of password file as many NCSA-compliant web servers. No visible documentation, but the code is readable.

Pluggable Authentication Module. Ideal for PAM-enabled systems like Debian Linux. PAM is configurable to use a variety of authentication systems. Instructions are in the comments in the .c file.

Authenticates against an SMB server such as Windows NT or Samba. See the ReadMe file in the SMB module directory.

Authenticates off the Unix password or shadow password file, or similar files which can be read by the C getpwnam() library function. There is no visible documentation or readable code. man getpwnam discusses the function. To use the shadow password file, the authenticator would need to be setuid root.

Contributed authentication modules

The contributed authentication modules are available at At the time of writing, there is a RADIUS authenticator, a modification of the standard LDAP authenticator for non-anonymous servers, and a patch which supports static and dynamic LDAP group look-ups.

How Squid processes authentication

Squid uses sub-processes to process authentication requests to avoid being blocked by slow connections. The authentication sub-processes are connected to Squid by standard Unix pipes and Squid communicates with them via stdin and stdout. The sub-process responds with "OK" or "ERR", depending on the success of the authentication.

Because every request must be authenticated, Squid caches the name/password pairs along with the results from successful authentications for a configurable number of seconds. This enables Squid to send requests for each item on a page, yet require only one authentication from the user's client.

Because of the cache, it is impractical for multiple users to share a login name. Squid uses splay trees to handle the internal cache; these don't respond well to duplicate keys.

Caveats and gotchas

Final words

Now the boss is off your neck and your proxy authentication is working -- go grab yourself a drink and put your feet up. Unless he's after you to do the next job....

Further reading

Jennifer Vesperman is the author of Essential CVS. She writes for the O'Reilly Network, the Linux Documentation Project, and occasionally Linux.Com.

Return to the Linux DevCenter.

Copyright © 2009 O'Reilly Media, Inc.