by Gary Lee

htpasswd, the Zen or Equivalent of - more about setting up password protection.

I used to daydream about sitting on a bus when suddenly a redheaded goddess comes up to me and says "I read your article on weeb tech, and ever since I've wanted to do lewd, crude, unmentionable-in-polite-company things to you." Alas, the closest thing to my dream occurred when I saw my old friend Regent, one of the driving forces behind Switch Magazine, on the bus and he suggested I write about how to display custom messages when someone fails to enter a correct password to a protected web page. I will try to work out the bitter frustration of an unrealized fantasy by discussing that topic.
September 1, 1999

Background

An earlier article, htpasswd, the Zen or equivalent of, tried to break every grammar rule in the book while imparting a little information on how to add password protection to certain sections of your web site. It generated the largest response of all my articles (one e-mail). 100% of the response was directed at my description of what happens if you enter a wrong username/password:

If you enter the wrong combination, you receive a terse, paranoia-inducing message stating that you failed.

Mr. Response proceeded to tell me that there are ways to customize the failure message, and he is right. The implication that I am a doofus is also correct. I was reawakened to this loose end by Regent, and now I will tie it up to appease the gods into sending me that redheaded goddess.

Foreground

Let's focus on a common configuration for the ordinary person, a UNIX server running Apache. Unfortunately, custom failure messages requires the cooperation of the system administrators. Unless you are a business client with your own domain name, etc., I doubt you'll get it. You'll soon see why....

srm.conf

In the conf directory of Apache (sometimes located at /usr/local/etc/httpd/conf/), there is a file called srm.conf. At the bottom of the file, you should see something like:

# Customizable error response (Apache style)
#  these come in three flavors
#
#    1) plain text
#ErrorDocument 500# "The server made a boo boo.
#  n.b.  the (") marks it as text, it does not get output
#
#    2) local redirects
#ErrorDocument 404 /missing.html
#  to redirect to local url /missing.html
#ErrorDocument 404 /cgi-bin/missing_handler.pl
#  n.b. can redirect to a script or a document
# using server-side-includes.
#
#    3) external redirects
#ErrorDocument 402
# http://other.server.com/subscription_info.html
#

All these lines are comments (denoted by the # character). You can see the format for displaying a particular URL for a particular error is:

ErrorDocument xxx URL

where xxx is the error code and URL is the URL of the page that will show up upon failure. All you have to do is add a line in the above format to srm.conf. Since this is an important configuration file, only authorized personnel will be able to make the modification. You will have to bribe them accordingly.

There are two problems with this method. One, you have to know the error codes, or in this case, the error code for a failed authorization. There are several URLs where you can find codes. If you look at http://www.w3.org/Protocols/HTTP/HTRESP.html, you might realize that the error code we want is 401. It might not be totally obvious from the given definition, but that's the one we want (I think).

So the line we want added would be:

ErrorDocument 401 (appropriate URL)

Afterwards, you just have to create the page at the appropriate URL.

Problem number 2 is not really your problem, but everyone else's problem. This line will redirect all authentication errors from everyone's web sites on the server to your custom error page. Sometimes this is desired. For example, if you screw up any GeoCities URL, you end up at the same friendly GeoCities page with pointers to all things GeoCities. However, this is bad if someone wants to display a message with her corporate logo, and you want to display your own logo. You can see the dilemma of the sysadmins, so don't yell at them if they don't fulfill your request. Especially if you don't want them to post your juicier private e-mails on some perverted newsgroup.

httpd.conf

However, if you have your own domain name, you might be in luck. Apache configures virtual hosts in the file httpd.conf . If you look at the bottom of that file, you will see something like:

# Any httpd.conf or srm.conf directive may go into
# a VirtualHost command.
# See alto the BindAddress entry.
 
#<VirtualHost host.some_domain.com>
#ServerAdmin webmaster@host.some_domain.com
#DocumentRoot /www/docs/host.some_domain.com
#ServerName host.some_domain.com
#ErrorLog logs/host.some_domain.com-error_log
#TransferLog logs/host.some_domain.com-access_log
#</VirtualHost>

Just like in srm.conf, the # character denotes a comment. The most informative comment is the first line. You may recall that the ErrorDocument line was added in srm.conf. Well, according to the first line, we can do it here, too.

So, a sample entry might look like:

<VirtualHost www.meep.com>
stuff...
ErrorDocument 401 /sucks_to_be_you.html
</VirtualHost>

<VirtualHost www.switchmag.com>
stuff...
ErrorDocument 401 /please_try_again.html
</VirtualHost>

Now, a separate message will be displayed upon authentication failures, depending on whether it occurred on a meep or a switchmag page. Nifty, eh?

That should tie up any loose ends.

Oh, except for tips on how to bribe sysadmins into doing what you want. Food is always the safest squeeze. Personally, I find redheads an adequate substitute.

More htpasswd stuff ==>