Authentication is any process by which you verify that someone is who they claim they are. In this article, Rich Bowen introduces some basic methods of authenticating users under Apache.
Authentication is any process by which you verify that someone is who they
claim they are. Authorization is any process by which someone is allowed to be
where they want to go, or to have information that they want to have.
If you have information on your Web site that is sensitive or intended for
only a small group of people, the techniques in this article will help you make
sure that the people that see those pages are the people that you wanted to see
This is the first in a two-part series. In this article, I'm going to cover
the standard way of protecting parts of your Web site that most of you are
going to use. In the next part I'll talk about using databases, rather than
text files, to contain your user and group information. Somewhere in here I'll
talk about using things other than usernames and passwords to protect your web
site from "intruders"--such as the IP address of the visitor.
Everything from here on assumes that your web server permits
.htaccess files. This is something that your server administrator
(assuming that's not you) should easily be able to tell you and set up for you.
The relevant directive is the
And you'll need to know a little bit about the directory structure of your
server, in order to know where some files are kept. This should not be terribly
difficult, and I'll try to make this clear when we come to that point.
Here's the basics of password protecting a directory on your server.
You'll need to create a password file. This file should be placed somewhere
outside of your document directory. This is so that folks cannot download the
password file. For example, if your documents are served out of
/usr/local/apache/htdocs you might want to put the password
To create the file, use the
htpasswd utility that came with
Apache. This is located in the
bin directory of wherever you
installed Apache. To create the file, type:
htpasswd -c /usr/local/apache/passwd/password rbowen
htpasswd will ask you for the password and then ask you to type
it again to confirm it:
# htpasswd -c /usr/local/apache/passwd/passwords rbowen
New password: mypassword
Re-type new password: mypassword
Adding password for user rbowen
htpasswd is not in your path, of course you'll have to type
the full path to the file to get it to run. On my server, it's located at
Next, you'll need to create a file in the directory you want to protect.
This file is usually called
.htaccess, although on Windows it's
htaccess (without the leading period).
.htaccess needs to contain the following lines:
AuthName "By Invitation Only"
require user rbowen
The next time that you load a file from that directory, you should see the
familiar username/password dialog box pop up. If you don't chances are pretty
good that you are not permitted to use
.htaccess files in the
directory in question.
The directives above only let one person (specifically someone with a
) into the directory. In most cases, you'll want
to let more than one person in. This is where the
comes in. In the example above, we've pointed
, which is Unix-speak for "nowhere" or
"off into space." (The Windows NT equivalent of this is
If you want to let more than one person in, you'll need to create a group
file that associates group names with a list of users in that group. The format
of this file is pretty simple, and you can create it with your favorite editor.
The contents of the file will look like this:
GroupName: rbowen dpitts sungo rshersey
That's just a list of the members of the group in a long line separated by
To add a user to your already existing password file, type:
htpasswd /usr/local/apache/passwd/password dpitts
You'll get the same response as before, but it will be appended to the
existing file, rather than creating a new file. (It's the
makes it create a new password file.)
Now, you need to modify your
.htaccess file to look like the
AuthName "By Invitation Only"
require group GroupName
Now, anyone that is listed in the group
GroupName and has an
entry in the
password file, will be let in if they type the
There's another way to let multiple users in that is less specific. Rather
than creating a group file, you can just use the following directive:
Using that rather than the
require user rbowen line will allow
anyone in that is listed in the password file and who correctly enters their
password. You can even emulate the group behavior here by keeping a separate
password file for each group. The advantage of this approach is that Apache
only has to check one file, rather than two. The disadvantage is that you have
to maintain a bunch of password files, and remember to reference the right one
Because of the way that basic authentication is specified, your username and
password must be verified every time you request a document from the server.
This is even if you're reloading the same page, and for every image on the page
(if they come from a protected directory). As you can imagine, this slows
things down a little. The amount that it slows things down is proportional to
the size of the password file, because Apache must open up that file and go
down the list of users until it gets to your name. And it has to do this every
time a page is loaded.
A consequence of this is that there's a limit to how many users you can put
in one password file. I don't exactly know what that limit is, but I've
experienced problems when I've put more than about 1,500 users in one file.
People are denied access, even though you know that they have a valid
username and password. It appears that what's happening is that it just takes
too long to look up the password, and in the meantime, access is denied.
In the next article, we'll look at one possible solution to this problem.
This may seem a little random, but it looked like a good time to throw this
There are two sets of Perl modules available for managing your password
files and group files with Perl.
The first one, which is probably the recommended one, is the
HTTPD-User-Manage package, which you can obtain from CPAN (http://www.cpan.org/modules/by-module/HTTPD/),
allows you to manage a variety of authentication files on a variety of web
servers. It is extremely full-featured and lets you do all the sorts of things
that you expect to be able to do. These modules were written by Lincoln Stein
and Doug MacEachern.
The other set of modules I really only mention as shameless self-promotion.
Apache::Htpasswd, by Kevin Meltzer, and
Apache::Htgroup, by me, provide a simpler interface to managing
password and group files specifically for Apache. These modules are also
available on CPAN.
Authentication by username and password is only part of the story.
Frequently you want to let people in based on something other than who they
are. Something such as where they are coming from.
deny directives let you allow and
deny access based on the host name, or host address, of the machine requesting
a document. The directive goes hand-in-hand with these is the
order directive, which tells Apache in which order to apply the
The usage of these directives is:
allow from address
where address is an IP address (or a partial IP address) or a fully
qualified domain name (or a partial domain name).
For example, if you have someone spamming your message board, and you want
to keep them out, you could do the following:
deny from 188.8.131.52
Visitors coming from that address will not be able to see the content behind
this directive. If, instead, you have a machine name, rather than an IP
address, you can use that:
deny from dc.numbersusa.com
And, if you'd like to block access from an entire domain, you can specify
just part of an address or domain name:
deny from 192.101.205
deny from cyberthugs.com
deny from ke
order will let you be sure that you are actually
restricting things to the group that you want to let in, by combining a
deny and an
deny from all
allow from dev.rcbowen.com
Listing just the
allow directive would not do what you want,
because it will let folks from that host in, in addition to letting everyone
in. What you want is to let only those folks in.
You should also read the documentation for
which contains some more information about how this all works. And the FAQ on
the Apache site has some good stuff about authentication, starting at
Next week, I'll talk about
mod_auth_mysql, which are two ways to authenticate against a
database, rather than against a text-file password list. This is much faster.