Back to course home page

Putting cookie-based protection onto selected directories, for Apache 1.3 server.

Robert K. Moniot

November 14, 2001

This document is a supplement to the information about setting up password protection using the .htaccess mechanism. Cookie-based authentication uses .htaccess files and a password file in the same way as regular .htaccess does, but it allows a cookie to substitute for the authentication. This means that a visitor from a machine with a valid authentication cookie will not need to provide the username and password information: this information is provided by the cookie. The description here assumes that authentication information is kept in a flat password file. Cookies can be also used with database authentication methods.

1. Cookie authentication using the Apache web server requires the installation of a third-party module called mod_auth_cookie. This is available from various places. For instance, Red Hat's contrib directory provides an RPM called apache-contrib that includes this module. After installing the module, the httpd configuration file is edited to uncomment the lines

        LoadModule cookie_auth_module modules/mod_auth_cookie.so
   
        AddModule mod_auth_cookie.c
   

   This has already been done on storm.

   In essence, what this module does is to collect the cookie if it exists, and convert it into a Basic Authorization header. This information is then used by the web server to grant or deny access to files and directories in the same way as if the information had been provided by an Authorization header.

2. Set up the password file in the same way as for regular .htaccess authentication.

3. In the directory to be protected, create the .htaccess file with the same contents as for regular .htaccess authentication, except for one additional directive:

        AuthCookieName VisitorID
   

   where VisitorID is the name of the cookie that will be set to provide authentication. The value of the cookie will be a username:password pair, with the password in clear, not encrypted form.

4. When a new visitor comes to the site, a CGI should present a fill-in form to register the visitor and establish a username and password, for instance by asking the user to specify what password they desire. The CGI that processes the form validates the authentication information and then sets a cookie containing this information. On subsequent visits to the protected site, the cookie will be sent and will provide authentication transparently. The cookie name must agree with the name specified in the AuthCookieName directive in the .htaccess file.

   (Note that if a visitor without a cookie goes directly to the protected site, bypassing the registration form, the browser will present a log-in box that will work in the same way as for normal access control. This allows a registered user to enter the protected site from a machine other than the one where the cookie is stored.)

Here is an example of the section of a CGI that processes the registration form and sets the cookie. Not shown is code that sets $user and $pass to the values provided on the registration form and validates these for acceptable form. Also not shown is code that adds the username and encrypted password to the password file.

   $cookie = "$user:$pass";
   print "Set-Cookie: VisitorID=$cookie; path=/~webber/membersonly/;
 expires=$expires;\n";
   print "Content-type: text/html\n\n";
     ...   # rest of page content here

(The username webber should be replaced with your own username, and the directory membersonly should be replaced with the name of the protected directory.)