Next Previous Contents

23. Authentication

23.1 How does Proxy Authentication work in Squid?

Note: The information here is current for version 2.4.

Users will be authenticated if squid is configured to use proxy_auth ACLs (see next question).

Browsers send the user's authentication credentials in the Authorization request header.

If Squid gets a request and the http_access rule list gets to a proxy_auth ACL, Squid looks for the Authorization header. If the header is present, Squid decodes it and extracts a username and password.

If the header is missing, Squid returns an HTTP reply with status 407 (Proxy Authentication Required). The user agent (browser) receives the 407 reply and then prompts the user to enter a name and password. The name and password are encoded, and sent in the Authorization header for subsequent requests to the proxy.

NOTE: The name and password are encoded using ``base64'' (See section 11.1 of RFC 2616). However, base64 is a binary-to-text encoding only, it does NOT encrypt the information it encodes. This means that the username and password are essentially ``cleartext'' between the browser and the proxy. Therefore, you probably should not use the same username and password that you would use for your account login.

Authentication is actually performed outside of main Squid process. When Squid starts, it spawns a number of authentication subprocesses. These processes read usernames and passwords on stdin, and reply with "OK" or "ERR" on stdout. This technique allows you to use a number of different authentication schemes, although currently you can only use one scheme at a time.

The Squid source code comes with a few authentcation processes. These include:

In order to authenticate users, you need to compile and install one of the supplied authentication modules, one of the others, or supply your own.

You tell Squid which authentcation program to use with the authenticate_program option in squid.conf. You specify the name of the program, plus any command line options if necessary. For example:

authenticate_program /usr/local/squid/bin/ncsa_auth /usr/local/squid/etc/passwd

23.2 How do I use authentication in access controls?

Make sure that your authentication program is installed and working correctly. You can test it by hand.

Add some proxy_auth ACL entries to your squid configuration. For example:

acl foo proxy_auth REQUIRED
acl all src 0/0
http_access allow foo
http_access deny all
The REQURIED term means that any authenticated user will match the ACL named foo.

Squid allows you to provide fine-grained controls by specifying individual user names. For example:

acl foo proxy_auth REQUIRED
acl bar proxy_auth lisa sarah frank joe
acl daytime time 08:00-17:00
acl all src 0/0
http_access allow bar
http_access allow foo daytime
http_access deny all
In this example, users named lisa, sarah, joe, and frank are allowed to use the proxy at all times. Other users are allowed only during daytime hours.

23.3 Does Squid cache authentication lookups?

Yes. Successful authentication lookups are cached for one hour by default. That means (in the worst case) its possible for someone to keep using your cache up to an hour after he has been removed from the authentication database.

You can control the expiration time with the authenticate_ttl option.

23.4 Are passwords stored in clear text or encrypted?

Squid stores cleartext passwords in itsmemory cache.

Squid writes cleartext usernames and passwords when talking to the external authentication processes. Note, however, that this interprocess communication occors over TCP connections bound to the loopback interface. Thus, its not possile for processes on other comuters to "snoop" on the authentication traffic.

Each authentication program must select its own scheme for persistent storage of passwords and usernames.

23.5 How do I use the Winbind authenticators?

by Jerry Murdock

Winbind is a recent addition to Samba providing some impressive capabilities for NT based user accounts. From Squid's perspective winbind provides a robust and efficient engine for both basic and NTLM challenge/response authentication against an NT domain controller.

The winbind authenticators have been used successfully under Linux, FreeBSD and Solaris.

Supported Samba Releases

Samba 2.2.x releases 2.2.4 and later are officially supported.

Squid 2.5 uses an internal Samba interface to communicate with the winbindd daemon. It is therefore sensitive to any changes the Samba team may make to the interface.

If using Samba 2.2.4 or 2.2.5 then the Squid winbind helpers will work as is.

With Samba 2.2.6, the winbindd interface changed and Squid 2.5 will not work as distributed. Replacing the winbindd_nss.h file in Squid's helpers/basic_auth/winbind, helpers/ntlm_auth/winbind and helpers/external_acl/wb_group/ directories with the version in Samba's source/nsswitch directory is needed for the helpers to work properly.

Samba 3.0a17 and 3.0a18 implement the same winbindd interface as 2.2.4+ and are known to work.

With Samba 3.0a19, the winbindd interface changed and Squid 2.5 will not work as distributed. Replacing the winbindd_nss.h file in Squid's helpers/basic_auth/winbind, helpers/ntlm_auth/winbind and helpers/external_acl/wb_group/ directories with the version in Samba's source/nsswitch directory has been reported to work.

The approach may be applicable for later Samba 3.0 versions as long as the interface does not change significantly, but there is no guarantees.

The Samba and Squid teams are actively working together to insure future Samba stable releases will be supported.

Configure Samba

Build/Install Samba

Samba must be built with configure options:

        --with-winbind-auth-challenge (needed for ntlm)

Optionally, if building Samba 2.2.5, apply the smbpasswd.diff patch. See SMBD and Machine Trust Accounts below to determine if the patch is worthwhile.

Test Samba's winbindd

  1. Edit smb.conf for winbindd functionality. The following entries in the [global] section of smbd.conf may be used as a template.
    workgroup = mydomain
    password server = myPDC
    security = domain
    winbind uid = 10000-20000
    winbind gid = 10000-20000
    winbind use default domain = yes 
  2. Join the NT domain as outlined in the winbindd man page for your version of samba.
  3. Test winbindd functionality. NOTE: both plaintext and challenge/response should return "succeeded." If there is no "challenge/response" status returned then Samba was not built with "--with-winbind-auth-challenge" and cannot support ntlm authentication.

SMBD and Machine Trust Accounts

Samba 2.2.x

Samba's smbd daemon, while not strictly required by winbindd may be needed to manage the machine's trust account.

Well behaved domain members change the account password on a regular basis. Windows and Samba servers default to changing this password every seven days.

The Samba component responsible for managing the trust account password is smbd. Smbd needs to receive requests to trigger the password change. If the machine will be used for file and print services, then just running smbd to serve routine requests should keep everything happy.

However, in cases where Squid's winbind helpers are the only reason Samba components are running, smbd may sit idle. Indeed, there may be no other reason to run smbd at all.

There are two sample options to change the trust account. Either may be scheduled daily via a cron job to change the trust password. is a sample perl script to load smbd, connect to a Samba share using smbclient, and generate enough dummy activity to trigger smbd's machine trust account password change code.

smbpasswd.diff is a patch to Samba 2.2.5's smbpasswd utility to allow changing the machine account password at will. It is a minimal patch simply exposing a command line interface to an existing Samba function.

Note: This patch has been included in Samba as of 2.2.6pre2.

Once patched, the smbpasswd syntax to change the password is:

        smbpasswd -t DOMAIN -r PDC

Samba 3.x

The Samba team has incorporated functionality to change the machine trust account password in the new "net" command. A simple daily cron job scheduling "net rpc changetrustpw" is all that is needed.

Configure Squid

Build/Install Squid

Squid must be built with the configure options:


Test Squid without auth

Before going further, test basic Squid functionality. Make sure squid is functioning without requiring authorization.

Test the helpers

Testing the winbind ntlm helper is not really possible from the command line, but the winbind basic authenticator can be tested like any other basic helper:

        # /usr/local/squid/libexec/wb_auth -d
        /wb_auth[65180](wb_basic_auth.c:136): basic winbindd auth helper ...
        mydomain\myuser mypasswd                   
        /wb_auth[65180](wb_basic_auth.c:107): Got 'mydomain\myuser mypasswd' from squid (length: 24).
        /wb_auth[65180](wb_basic_auth.c:54): winbindd result: 0
        /wb_auth[65180](wb_basic_auth.c:57): sending 'OK' to squid
The helper should return "OK" if given a valid username/password.

Edit squid.conf

  1. Setup the authenticators.

    Add the following to enable both the winbind basic and ntlm authenticators. IE will use ntlm and everything else basic:

            auth_param ntlm program /usr/local/squid/libexec/wb_ntlmauth         
            auth_param ntlm children 5
            auth_param ntlm max_challenge_reuses 0
            auth_param ntlm max_challenge_lifetime 2 minutes
            auth_param basic program /usr/local/squid/libexec/wb_auth
            auth_param basic children 5
            auth_param basic realm Squid proxy-caching web server
            auth_param basic credentialsttl 2 hours

  2. Add acl entries to require authentication:
            acl AuthorizedUsers proxy_auth REQUIRED
            http_access allow all AuthorizedUsers

Test Squid with auth

  1. Internet Explorer:

    Test browsing through squid with IE. If logged into the domain, a password prompt should NOT pop up.

    Confirm the traffic really is being authorized by tailing access.log. The domain\username should be present.

  2. Netscape, mozilla, opera...:

    Test with a non-IE browser. A standard password dialog should appear.

    Entering the domain should not be required if the user is in the default domain and "winbind use default domain = yes" is set in smb.conf. Otherwise, the username must be entered in "domain\username" format.

If no usernames appear in access.log and/or no password dialogs appear in either browser, then the acl/http_access portions of squid.conf are not correct.


Samba Winbind Overview

Joining a Domain in Samba 2.2.x

winbindd man page

wbinfo man page

nmbd man page

smbd man page

smb.conf man page

smbclient man page

Next Previous Contents