make htpasswd
in the support directory to compile it (you might need to modify the
Makefile first, since any configuration you did when compiling the
server itself is not available to this makefile). After compilation,
you can either leave the htpasswd binary where it is, or more it to a
directory on your path (e.g. /usr/local/bin). In the former case, you
will need to remember to give the full pathname to run it. The
examples here will assume that it is installed somewhere on your path.
[INLINE]
Using htpasswd
To create a new user file and add the username "martin" with the
password "hampster" to the file /usr/local/etc/httpd/users:
htpasswd -c /usr/local/etc/httpd/users martin
The -c argument tells htpasswd to create new users file. When you run
this command, you will be prompted to enter a password for martin, and
confirm it by entering it again. Other users can be added to the
existing file in the same way, except that the -c argument is not
needed. The same command can also be used to modify the password of an
existing user.
After adding a few users, the /usr/local/etc/httpd/users file might
look like this:
martin:WrU808BHQai36
jane:iABCQFQs40E8M
art:FAdHN3W753sSU
The first field is the username, and the second field is the encrypted
password.
[INLINE]
Configuring the Server
To get the server to use the usernames and passwords in this file, you
need to configure a realm. This is a section of your site that is to
be restricted to some or all of the users listed in this file. This is
typically done on a per-directory basis, with a directory (and all its
subdirectories) being protected (Apache 1.2. will let you protect
individual files). The directives to create the protected area can be
placed in a .htaccess file in the directory concerned, or in a
<Directory> section in the access.conf file.
To allow a directory to be restricted within a .htaccess file, you
first need to ensure that the access.conf file allows user
authentication to be setup in a .htaccess file. This is controlled by
the AuthConfig override. The access.conf file should include
AllowOverride AuthConfig to allow the authentication directives to be
used in a .htaccess file.
To restrict a directory to any user listed in the users file just
created, you should create a .htaccess file containing:
AuthName "restricted stuff"
AuthType Basic
AuthUserFile /usr/local/etc/httpd/users
require valid-user
The first directive, AuthName, specifies a realm name for this
protection. Once a user has entered a valid username and password, any
other resources within the same realm name can be accessed with the
same username and password. This can be used to create two areas which
share the same username and password.
The AuthType directive tells the server what protocol is to be used
for authentication. At the moment, Basic is the only method available.
However a new method, Digest, is about to be standardised, and once
browsers start to implement it, digest authentication will provide
more security than the basic authentication.
AuthUserFile tells the server the location of the user file created by
htpasswd. A similar directive, AuthGroupFile, can be used to tell the
server the location of a groups file (see below).
These four directives have between them tell the server where to find
the usernames and passwords and what authentication protocol to use.
The server now knows that this resource is restricted to valid users.
The final stage is to tell the server which usernames from the file
are valid for particular access methods. This is done with the require
directive. In this example, the argument valid-user tells the server
that any username in the users file can be used. But it could be
configured to allow only certain users in:
require user martin jane
would only allow users martin and jane access (after they entered a
correct password). If user art (or any other user) tried to access
this directory - even with the correct password - they would be
denied. This is useful to restrict different areas of your server to
different people with the same users file. If a user is allowed to
access the different areas, they only have to remember a single
password. Note that if the realm name differs in the different areas,
the user will have to re-enter their password.
[INLINE]
Using Groups
If you want to allow only selected users from the users file in to a
particular area, you can list all the allowed usernames on the require
line. However this means you are building username information into
your .htaccess files, and might not been convenient if there are a lot
of users, and . Fortunately there is a way round this, using a group
file. This operates in a similar way to standard Unix groups: any
particular user can be a member of any number of groups. You can then
use the require line to restrict users to one or more particular
groups. For example, you could create a group called staff containing
users who are allowed to access internal pages. To restrict access to
just users in the staff group, you would use
require group staff
Multiple groups can be listed, and require user can also be given, in
which case any user in any of the listed groups, or any user listed
explicitly, can access the resource. For example
require group staff admin
require user adminuser
which would allow any user in group staff or group admin, or the user
adminuser, to access this resource after entering a valid password.
A group file consists of lines giving a group name followed by a
space-separated list of users in that group. For example:
staff:martin jane
admin:art adminuser
The AuthGroupFile directive is used to tell the server the location of
the group file. Note that the maximum line length within the group
file in about 8000 characters (actually 8kB). If you have more users
in a group than will fit within that line length, you can have more
than one line with the same group name within the file.
[INLINE]
Problems with Large Numbers of Users
Using htpasswd to create a text list of users, and maintaining a list
of groups in a plain text file is relatively easy. However if the
number of users becomes large, the server has a lot of processing to
do to find a user's group and password details. This processing has to
be done for every request inside the protected area (even though the
user only enters their password once, the server has to
re-authenticate them on every request). This can be slow with a lot of
users, and adds to the server load. Much faster access is possible
using DBM format files. This allows the server to do a very quick
lookup of names, without having to read through a large text file.
However managing DBM files is more complex. Apache Week will cover the
use of DBM authentication in a future issue.
[INLINE]
Other Ways of Storing User Details
While Apache by default can only access user details in plain text
files, various add-on modules are available to allow user details to
be stored in databases. Besides DBM format (available with the
mod_auth_dbm module), user and group lists can be stored in DB format
files (with mod_auth_db). Or full databases can be used, such as mSQL
(with mod_auth_msql), Postgres95 (mod_auth_pg95) or any DBI-compatible
database (mod_auth_dbi).
It is also possible to have an arbitrary external program check
whether the given username and password is valid (this could be used
to write an interface to check against any other database or
authentication service). Modules are also available to check against
the system password file, or to use a Kerberos system. See the feature
on Adding Modules for more information.
[INLINE]
Limiting Methods Differently
In the example .htaccess file above, the require directory is not
given inside a <Limit> section. This is valid in Apache, and means it
applies to all request methods. In other servers and most example
.htaccess files, the require directive is given inside a <Limit>
section, such as this:
<Limit GET POST PUT>
require valid-user
</Limit>
In Apache it is better to omit the <Limit> and </Limit> lines, to
ensure that the protection applies to all methods. However, this
format can be used to limit particular methods. For example, to limit
just the POST method, use
AuthName "restrict posting"
AuthType Basic
AuthUserFile /usr/local/etc/httpd/users
<Limit POST>
require group staff
<Limit>
Now only members of the group staff will be allowed to POST. Other
users (unauthenticated) can use other methods, such as GET. This could
be used to allow a CGI program to be accessed by anyone, but only
authorised uses can POST information to it.
[INLINE]
Restricting By Hostname or Username
One feature of the NCSA server is that is allows a request to be
allowed if it comes from within a particular domain name, or if not,
to ask for a valid username and password (using the satisfy
directive). This is a combination of restricting by username and by
the user's hostname. Unfortunately Apache currently cannot do this.
[INLINE]
How WWW Authentication Works
The method used in HTTP for user authetication is quite simple. Since
HTTP is a stateless protocol - that is, the server does not remember
any information about a request once it has finished - the browser
needs to resend the username and password on each request. Here is how
it works.
On the first access to an authenticated resource, the server will
return a 401 status ("Unauthorized") and include a WWW-Authenticate
response header. This will contain the authentication scheme to use
(at the moment, only Basic is allowed) and the realm name. The browser
should then ask the user to enter a username and password. It then
requests the same resource again, this time including a Authorization
header which contains the scheme name ("Basic") and the username and
password entered.
The server checks the username and password, and if they are valid,
returns the page. If the password is not valid for that user, or the
user is not allowed access because they are not listed on a require
user line or in a suitable group, the server returns a 401 status as
before. The browser can then ask the user to retry their username and
password.
Assuming the username and password was valid, the user might next
request another resource which is protected. In this case, the server
would respond with a 401 status, and the browser could send the
request again with the user and password details. However this would
be slow, so instead the browser sends the Authorization header on
subsequent requests. Note that the browser must ensure that it only
sends the username and password to further requests on the same server
(it would be insecure to send those details if the user moved onto a
different server).
The browser needs to remember the username and password entered, so it
can send them with future requests from the same server. Note that
this can cause problems when testing authentication, since the browser
remembers the first username and password that works. It can be
difficult to force the browser to ask for a new username and password.
[INLINE]
Security and Digest Authentication
While authentication does allow resources to be restricted to
particular users, there are potential security issues. Some of these
are:
* Care must be taken to ensure that the resource is restricted
against all methods. Use of <Limit GET>, for instance, leaves POST
and other request methods unprotected.
* The username and password are stored in a plain text file. While
the password is encrypted, it is not completely safe against
decryption, so the file should not be accessible to other users on
the system. More importantly, it should not be placed under the
document root where users from other sites could access it.
* The username and password is as secure as any username/password
system, in that end-users should not tells others their password,
or write it down, or make it easily guessable.
* The Basic authentication scheme transmits passwords across the
Internet unencrypted, so they could be intercepted. The Digest
method, see below, is intended to address this issue.
The Digest Authentication scheme will make the sending of passwords
across the Internet more secure. It effectively encrypts the password
before it is sent such that the server can decrypt it. It works
exactly the same as Basic authentication as far as the end-user and
server administrator is concerned. The use of Digest authentication
will depend on whether browser authors write it into their products.
Apache can already do Digest authentication, when compiled with the
mod_digest module (supplied with the Apache distribution).
[INLINE]
More Information
For more information about how user authentication works on the
Internet, see the HTTP/1.0 and HTTP/1.1 documents, available from the
Apache Week links page. Also available there is a link to the draft
Digest Authentication specification.
For basic information about setting up user authentication, see the
NCSA Tutorial (most of which also applies to Apache).
For modules which allow usernames, groups and passwords to be stored
in database format files, or databases themselves, see this Apache
Week feature on Adding Modules.
_________________________________________________________________
Comments or criticisms? Please email us at editors@apacheweek.com.
Apache Week is copyright 1996-1998 by C2Net Europe Limited. C2Net
sells network security and encryption products.