Basic authentication
As the name implies, basic authentication is the simplest method of authentication, and for
a long time was the most common authentication method used. However, other methods of
authentication have recently passed basic in common usage, due to usability issues that will
be discussed in a minute.
How basic authentication works
When a particular resource has been protected using basic authentication, Apache sends a 401
Authentication Required header with the response to the request, in order to notify the
client that user credentials must be supplied in order for the resource to be returned as
requested.
Upon receiving a 401 response header, the client's browser, if it supports basic
authentication, will ask the user to supply a username and password to be sent to the server.
If you are using a graphical browser, such as Netscape or Internet Explorer, what you will see
is a box which pops up and gives you a place to type in your username and password, to be sent
back to the server. If the username is in the approved list, and if the password supplied is
correct, the resource will be returned to the client.
Because the HTTP protocol is stateless, each request will be treated in the same way, even
though they are from the same client. That is, every resource which is requested from the
server will have to supply authentication credentials over again in order to receive the
resource.
Fortunately, the browser takes care of the details here, so that you only have to type in
your username and password one time per browser session - that is, you might have to type it
in again the next time you open up your browser and visit the same web site.
Along with the 401 response, certain other information will be passed back to the
client. In particular, it sends a name which is associated with the protected area of the web
site. This is called the realm, or just the authentication name. The client browser
caches the username and password that you supplied, and stores it along with the
authentication realm, so that if other resources are requested from the same realm, the same
username and password can be returned to authenticate that request without requiring the user
to type them in again. This caching is usually just for the current browser session, but some
browsers allow you to store them permanently, so that you never have to type in your password
again.
The authentication name, or realm, will appear in the pop-up box, in order to identify what
the username and password are being requested for.
Configuration: Protecting content with basic authentication
There are two configuration steps which you must complete in order to protect a resource
using basic authentication. Or three, depending on what you are trying to do.
- Create a password file
- Set the configuration to use this password file
- Optionally, create a group file
Create a password file
In order to determine whether a particular username/password combination is valid, the
username and password supplied by the user will need to be compared to some authoritative
listing of usernames and password. This is the password file, which you will need to create on
the server side, and populate with valid users and their passwords.
Because this file contains sensitive information, it should be stored outside of the
document directory. Although, as you will see in a moment, the passwords are encrypted in the
file, if a cracker were to gain access to the file, it would be an aid in their attempt to
figure out the passwords. And, because people tend to be sloppy with the passwords that they
choose, and use the same password for web site authentication as for their bank account, this
potentially be a very serious breach of security, even if the content on your web site is not
particularly sensitive.
Caution: Encourage your users to use a different password for your web site than for
other more essential things. For example, many people tend to use two passwords - one for all
of their extremely important things, such as the login to their desktop computer, and for
their bank account, and another for less sensitive things, the compromise of which would be
less serious.
To create the password file, use the htpasswd utility that came with Apache. This
will be located in the bin directory of wherever you installed Apache. For example,
it will probably be located at /usr/local/apache/bin/htpasswd if you installed Apache
from source.
To create the file, type:
htpasswd -c /usr/local/apache/passwd/passwords username
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
Note that in the example shown, a password file is being created containing a user called rbowen,
and this password file is being placed in the location /usr/local/apache/passwd/passwords.
You will substitute the location, and the username, which you want to use to start your
password file.
If htpasswd is not in your path, you will have to type the full path to the file
to get it to run. That is, in the example above, you would replace htpasswd with /usr/local/apache/bin/htpasswd
The -c flag is used only when you are creating a new file. After the first time,
you will omit the -c flag, when you are adding new users to an already-existing
password file.
htpasswd /usr/local/apache/passwd/passwords sungo
The example just shown will add a user named sungo to a password file which has
already been created earlier. As before, you will be asked for the password at the command
line, and then will be asked to confirm the password by typing it again.
Caution: Be very careful when you add new users to an existing password file that
you don't use the -c flag by mistake. Using the -c flag will create a new
password file, even if you already have an existing file of that name. That is, it will remove
the contents of the file that is there, and replace it with a new file containing only the one
username which you were adding.
The password is stored in the password file in encrypted form, so that users on the system
will not be able to read the file and immediately determine the passwords of all the users.
Nevertheless, you should store the file in as secure a location as possible, with whatever
minimum permissions on the file so that the web server itself can read the file. For example,
if your server is configured to run as user nobody and group nogroup, then
you should set permissions on the file so that only the webserver can read the file and only
root can write to it:
chown root.nogroup /usr/local/apache/passwd/passwords
chmod 640 /usr/local/apache/passwd/passwords
On Windows, a similar precaution should be taken, changing the ownership of the password
file to the web server user, so that other users cannot read the file.
Set the configuration to use this password file
Once you have created the password file, you need to tell Apache about it, and tell Apache
to use this file in order to require user credentials for admission. This configuration is
done with the following directives:
| AuthType |
Authentication type being used. In this case,
it will be set to Basic |
| AuthName |
The authentication realm or name |
| AuthUserFile |
The location of the password file |
| AuthGroupFile |
The location of the group file, if any |
| Require |
The requirement(s) which must be satisfied in
order to grant admission |
These directives may be placed in a .htaccess file in the particular directory
being protected, or may go in the main server configuration file, in a <Directory>
section, or other scope container.
The example shown below defines an authentication realm called ``By Invitation Only''. The
password file located at /usr/local/apache/passwd/passwords will be used to verify
the user's identity. Only users named rbowen or sungo will be granted
access, and even then only if they provide a password which matches the password stored in the
password file.
AuthType Basic
AuthName "By Invitation Only"
AuthUserFile /usr/local/apache/passwd/passwords
Require user rbowen sungo
The phrase ``By Invitation Only'' will be displayed in the password pop-up box, where the
user will have to type their credentials.
You will need to restart your Apache server in order for the new configuration to take
effect, if these directives were put in the main server configuration file. Directives placed
in .htaccess files take effect immediately, since .htaccess files are parsed
each time files are served.
The next time that you load a file from that directory, you will see the familiar
username/password dialog box pop up, requiring that you type the username and password before
you are permitted to proceed.
Note that in addition to specifically listing the users to whom you want to grant access,
you can specify that any valid user should be let in. This is done with the valid-user
keyword:
Require valid-user
Optionally, create a group file
Most of the time, you will want more than one, or two, or even a dozen, people to have
access to a resource. You want to be able to define a group of people that have access to that
resource, and be able to manage that group of people, adding and removing members, without
having to edit the server configuration file, and restart Apache, each time.
This is handled using authentication groups. An authentication group is, as you would
expect, a group name associated with a list of members. This list is stored in a group file,
which should be stored in the same location as the password file, so that you are able to keep
track of these things.
The format of the group file is exceedingly simple. A group name appears first on a line,
followed by a colon, and then a list of the members of the group, separated by spaces. For
example:
authors: rich daniel allan
Once this file has been created, you can Require that someone be in a particular
group in order to get the requested resource. This is done with the AuthGroupFile
directive, as shown in the following example.
AuthType Basic
AuthName "Apache Admin Guide Authors"
AuthUserFile /usr/local/apache/passwd/passwords
AuthGroupFile /usr/local/apache/passwd/groups
Require group authors
The authentication process is now one step more involved. When a request is received, and
the requested username and password are supplied, the group file is first checked to see if
the supplied username is even in the required group. If it is, then the password file will be
checked to see if the username is in there, and if the supplied password matches the password
stored in that file. If any of these steps fail, access will be forbidden.
Frequently asked questions about basic auth
The following questions tend to get asked very frequently with regard to basic
authentication. It should be understood that basic authentication is very basic, and so is
limited to the set of features that has been presented above. Most of the more interesting
things that people tend to want, need to be implemented using some alternate authentication
scheme.
How do I log out?
Since browsers first started implementing basic authentication, website administrators have
wanted to know how to let the user log out. Since the browser caches the username and password
with the authentication realm, as described earlier in this tutorial, this is not a function
of the server configuration, but is a question of getting the browser to forget the credential
information, so that the next time the resource is requested, the username and password must
be supplied again. There are numerous situations in which this is desirable, such as when
using a browser in a public location, and not wishing to leave the browser logged in, so that
the next person can get into your bank account.
However, although this is perhaps the most frequently asked question about basic
authentication, thus far none of the major browser manufacturers have seen this as being a
desirable feature to put into their products.
Consequently, the answer to this question is, you can't. Sorry.
How can I change what the password box looks like?
The dialog that pops up for the user to enter their username and password is ugly. It
contains text that you did not indicate that you wanted in there. It looks different in
Internet Explorer and Netscape, and contains different text. And it asks for fields that the
user might not understand - for example, Netscape asks the user to type in their ``User ID'',
and they might not know what that means. Or, you might want to provide additional explanatory
text so that the user has a better idea what is going on.
Unfortunately, these things are features of the browser, and cannot be controlled from the
server side. If you want the login to look different, then you will need to implement your own
authentication scheme. There is no way to change what this login box looks like if you are
using basic authentication.
How to I make it not ask me for my password the next time?
Because most browsers store your password information only for the current browser session,
when you close your browser it forgets your username and password. So, when you visit the same
web site again, you will need to re-enter your username and password.
There is nothing that can be done about this on the server side.
However, the most recent versions of the major browsers contain the ability to remember
your password forever, so that you never have to log in again. While it is debatable whether
this is a good idea, since it effectively overrides the entire point of having security in the
first place, it is certainly convenient for the user, and simplifies the user experience.
Why does it sometimes ask me for my password twice?
When entering a password-protected web site for the first time, you will occasionally
notice that you are asked for your password twice. This may happen immediately after you
entered the password the first time, or it may happen when you click on the first link after
authenticating the first time.
This happens for a very simple, but nonetheless confusing, reason, again having to do with
the way that the browser caches the login information.
Login information is stored on the browser based on the authentication realm, specified by
the AuthName directive, and by the server name. In this way, the browser can
distinguish between the Private authentication realm on one site and on another. So,
if you go to a site using one name for the server, and internal links on the server refer to
that server by a different name, the browser has no way to know that they are in fact the same
server.
For example, if you were to visit the URL http://example.com/private/, which
required authentication, your browser would remember the supplied username and password,
associated with the hostname example.com. If, by virtue of an internal redirect, or
fully-qualified HTML links in pages, you are then sent to the URL http://www.example.com/private/,
even though this is really exactly the same URL, the browser does not know this for sure, and
is forced to request the authentication information again, since example.com and www.example.com
are not exactly the same hostname. Your browser has no particular way to know that these are
the same web site.
Security caveat
Basic authentication should not be considered secure for any particularly rigorous
definition of secure.
Although the password is stored on the server in encrypted format, it is passed from the
client to the server in plain text across the network. Anyone listening with any variety of
packet sniffer will be able to read the username and password in the clear as it goes across.
Not only that, but remember that the username and password are passed with every request,
not just when the user first types them in. So the packet sniffer need not be listening at a
particularly strategic time, but just for long enough to see any single request come across
the wire.
And, in addition to that, the content itself is also going across the network in the clear,
and so if the web site contains sensitive information, the same packet sniffer would have
access to that information as it went past, even if the username and password were not used to
gain direct access to the web site.
Don't use basic authentication for anything that requires real security. It is a detriment
for most users, since very few people will take the trouble, or have the necessary software
and/or equipment, to find out passwords. However, if someone had a desire to get in, it would
take very little for them to do so.
|
