12.2 HTTP Basic Authentication
Basic authentication is the simplest and least secure that HTTP has to offer. It essentially transmits user passwords as cleartext, although they are encoded into printable characters. For example, if the user types her name as Fannie and her password as FuRpAnTsClUb, the user-agent first combines the two into a single string, with name and password separated by a colon:
Fannie:FuRpAnTsClUb
Then it encodes this string with base64 encoding, as defined in RFC 2045. It looks like this in the HTTP headers:
Authorization: Basic RmFubmllOkZ1UnBBblRzQ2xVYgo=
Anyone who happens to capture your users' HTTP requests can easily get both the username and password:
% echo RmFubmllOkZ1UnBBblRzQ2xVYgo= | /usr/local/lib/python1.5/base64.py -d Fannie:FuRpAnTsClUb
As required by the HTTP/1.1 RFC, Squid doesn't forward "consumed" authorization credentials to other servers. In other words, if the credentials are for access to Squid, the Authorization header is removed from outgoing requests.[1]
[1] Unless you configure a peer with the login=PASS option.
You'll notice that some of the Basic authenticators can be configured to check the system password file. Because Basic credentials aren't encrypted, it is a bad idea to combine login passwords with cache access passwords. If you choose to use the getpwnam authenticator, make sure you fully understand the implications of having your users' passwords transmitted in the clear across your network.
HTTP Basic authentication supports the following auth_param parameters:
auth_param basic program command
auth_param basic children number
auth_param basic realm string
auth_param basic credentialsttl time-specification
The program parameter specifies the command, including arguments, for the helper program. In most cases, this will be the pathname to one of the authentication helper programs that you compiled. By default, they live in /usr/local/squid/libexec.
The children parameter tells Squid how many helper processes to use. The default value is 5, which is a good starting point if you don't know how many Squid needs to handle the load. If you specify too few, Squid warns you with messages in cache.log.
The realm parameter is the authentication realm string that the user-agent should present to the user when prompting for a username and password. You can use something simple, such as "access to the Squid caching proxy."
The credentialsttl parameter specifies the amount of time that Squid internally caches authentication results. A larger value reduces the load on the external authenticator processes, but increases the amount of time until Squid detects changes to the authentication database. Note, this only affects positive results (i.e., successful validations). Negative results aren't cached inside Squid. The default TTL value is two hours.
Here is a complete example:
auth_param basic program /usr/local/squid/libexec/pam_auth auth_param basic children 10 auth_param basic realm My Awesome Squid Cache auth_param basic credentialsttl 1 hour acl KnownUsers proxy_auth REQUIRED http_access allow KnownUsers
Next I will discuss the Basic authentication helper programs that come with Squid.
12.2.1 NCSA
./configure enable-basic-auth-helpers=NCSA
The NCSA authentication helper is relatively popular due to its simplicity and history. It stores usernames and passwords in a single text file, similar to the Unix /etc/passwd file. This password file format was originally developed as a part of the NCSA HTTP server project.
You pass the path to the password file as the program's single command-line argument in squid.conf:
auth_param basic program /usr/local/squid/libexec/ncsa_auth
/usr/local/squid/etc/passwd
You can use the htpasswd program that comes with Apache to create and update the password file. Also, you can download it from http://www.squid-cache.org/htpasswd/. From that page, you can also download the chpasswd CGI script, which allows users to change their own passwords if necessary.
12.2.2 LDAP
./configure enable-basic-auth-helpers=LDAP
The LDAP helper interfaces to a Lightweight Directory Access Protocol server. The OpenLDAP libraries and header files must be installed before you can compile the squid_ldap_auth helper. You can find OpenLDAP at http://www.openldap.org/.
The squid_ldap_auth program requires at least two arguments: the base distinguished name (DN) and the LDAP server hostname. For example:
auth_param basic program /usr/local/squid/libexec/squid_ldap_auth -b "ou=people,dc=example,dc=com" ldap.example.com
The LDAP helper has a Unix manual page that describes all of its options and parameters. However, Squid's manual pages aren't normally installed when you run make install. You can read the manual page by locating it in the source tree and manually running nroff. For example:
% cd helpers/basic_auth/LDAP % nroff -man squid_ldap_auth.8 | less
12.2.3 MSNT
./configure enable-basic-auth-helpers=MSNT
The MSNT authenticator interfaces to a Microsoft NT domain database via the Server Message Block (SMB) protocol. It uses a small configuration file, named msntauth.conf, which must be placed in the $prefix/etc or sysconfidr directory. You can specify up to five NT domain controllers in the configuration file. For example:
server pdc1_host bdc1_host my_nt_domain server pdc2_host bdc2_host another_nt_domain
By default, the MSNT authenticator allows any user validated by the server. However, it also has the ability to allow or deny specific usernames. If you create an allowusers file, only the users listed there are allowed access to Squid. You might want to use this feature if you have a large number of users on the NT server, but only a small number who are allowed to use the cache. Alternatively, you can create a denyusers file. Any user listed in that file is automatically denied access, even before checking the allowusers file.
Alternatively, you can allow or deny specific usernames by placing them in the proxy_auth ACL as described in Section 6.1.2.12.
For additional documentation, see the README.html file in the helpers/basic_auth/MSNT directory.
12.2.4 Multi-domain-NTLM
./configure enable-basic-auth-helpers=multi-domain-NTLM
The multi-domain-NTLM authenticator is similar to MSNT. Both send queries to a Windows NT domain database. Whereas MSNT queries up to five domain controllers, the multi-domain-NTLM authenticator requires users to insert the NT domain name before their username, like this:
ntdomain\username
The multi-domain-NTLM helper program is a relatively short Perl script. It relies on the Authen::SMB package from CPAN (http://www.cpan.org). If you don't hardcode the domain controller hostnames in the Perl script, it utilizes the nmblookup program from the Samba package (www.samba.org) to discover them automatically.
The Perl script is named smb_auth.pl. It might look like this in squid.conf:
auth_param basic program /usr/local/squid/libexec/smb_auth.pl
Documentation for multi-domain-NTLM is thin, but if you understand Perl, you should be able to figure it out by reading the code.
12.2.5 PAM
./configure enable-basic-auth-helpers=PAM
In a sense, Pluggable Authentication Modules (PAM) are the glue between authentication methods (e.g., one-time passwords, kerberos, smart cards) and applications requiring authentication services (e.g., ssh, ftp, imap). Your system's /etc/pam.conf file describes which methods to use for each application.
To use Squid's PAM authentication helper, you need to add "squid" as a service in the /etc/pam.conf file and specify which PAM modules to use. For example, to use the Unix password file on FreeBSD, you might put this in pam.conf:
squid auth required pam_unix.so try_first_pass
|
The PAM authenticator is documented with a manual page that you can find in the helpers/basic_auth/PAM directory.
12.2.6 SASL
./configure enable-basic-auth-helpers=SASL
The Simple Authentication and Security Layer (SASL) is an IETF proposed standard, documented in RFC 2222. It is a protocol for negotiating security parameters for connection-based protocols (e.g., FTP, SMTP, HTTP). However, the SASL authenticator is similar to the PAM authenticator. It interfaces with a third-party library to query a number of different authentication databases.
Specifically, Squid's SASL authenticator requires the Cyrus SASL library developed by Carnegie Mellon University. You can find it at http://asg.web.cmu.edu/sasl/.
You can configure the SASL authenticator to check the traditional password file, the PAM system, or any of the other databases supported by CMU's library. For further information, see the README file in the helpers/basic_auth/SASL directory.
12.2.7 SMB
./configure enable-basic-auth-helpers=SMB
SMB is another authenticator for Microsoft Windows databases. The authenticator itself is a C program. That program executes a shell script each time it talks to the Windows domain controller. The shell script contains commands from the Samba package. Thus, you'll need to install Samba before using the SMB authenticator.
The SMB authenticator program, smb_auth takes the Windows domain name as an argument. For example:
auth_param basic program /usr/local/squid/libexec/smb_auth -W MYNTDOMAIN
You can list multiple domains by repeating the -W option. For full documentation, see http://www.hacom.nl/~richard/software/smb_auth.html.
12.2.8 YP
./configure enable-basic-auth-helpers=YP
The YP authenticator checks a system's "Yellow Pages" (a.k.a. NIS) directory. To use it with Squid, you need to provide the NIS domain name and the name of the password database, usually passwd.byname on the authenticator command line:
auth_param basic program /usr/local/squid/libexec/yp_auth my.nis.domain passwd.byname
The yp_auth program is relatively simple, but doesn't have any documentation.
12.2.9 getpwnam
./configure enable-basic-auth-helpers=getpwnam
This authenticator is simply an interface to the getpwnam( ) function found in the C library on Unix systems. The getpwnam( ) function looks in the system password file for a given username. If you use YP/NIS, getpwnam( ) checks those databases as well. On some operating systems, it may also utilize the PAM system. You can use this authenticator if your cache users have login accounts on the system where Squid is running. Alternatively, you could set up "nologin" accounts in the password file for your cache users.
12.2.10 winbind
./configure enable-basic-auth-helpers=winbind
Winbind is a feature of the Samba suite of software. It allows Unix systems to utilize Windows NT user account information. The winbind authenticator is a client for the Samba winbindd daemon. You must have Samba installed and the winbindd daemon running before you can use this authenticator.
The name of the winbind Basic authenticator is wb_basic_auth. It typically looks like this in squid.conf:
auth_param basic program /usr/local/squid/libexec/wb_basic_auth
12.2.11 The Basic Auth API
The interface between Squid and a Basic authenticator is quite simple. Squid sends usernames and passwords to the authenticator process, separated by a space and terminated by a newline. The authenticator reads the username and password pairs on stdin. After checking the credentials, the authenticator writes either OK or ERR to stdout.
|
You can easily test a Basic authenticator on the command line. Simply run the authenticator program in a terminal window and enter usernames and passwords. Or, you can do it like this:
% echo "bueller pencil" | ./ncsa_auth /tmp/passwd OK
Here is a simple template authenticator written in Perl:
#!/usr/bin/perl -wl
use URI::Escape;
$|=1; # don't buffer stdout
while (<>) {
($u,$p) = split;
$u = uri_unescape($u);
$p = uri_unescape($p);
if (&valid($u,$p)) {
print "OK";
} else {
print "ERR";
}
}
sub valid {
my $user = shift;
my $pass = shift;
...
}
