diff options
| author | Rich Bowen <rbowen@apache.org> | 2001-09-05 03:40:17 +0200 |
|---|---|---|
| committer | Rich Bowen <rbowen@apache.org> | 2001-09-05 03:40:17 +0200 |
| commit | f3ceda796970611522c38e4b96e60375768aa9b5 (patch) | |
| tree | e41f99c249eb63701f27e5705c8461072262ceb3 /docs/manual/howto/auth.html.en | |
| parent | There's no particular reason to advertise ApacheToday and/or (diff) | |
| download | apache2-f3ceda796970611522c38e4b96e60375768aa9b5.tar.xz apache2-f3ceda796970611522c38e4b96e60375768aa9b5.zip | |
First cut at authentication tutorial. Need to add section about
alternate authentication modules such as mod_auth_db, but this is a
decent start.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@90897 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs/manual/howto/auth.html.en')
| -rw-r--r-- | docs/manual/howto/auth.html.en | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/docs/manual/howto/auth.html.en b/docs/manual/howto/auth.html.en new file mode 100644 index 0000000000..9311ffcf81 --- /dev/null +++ b/docs/manual/howto/auth.html.en @@ -0,0 +1,318 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> + +<html> + <head> + <meta name="generator" content="HTML Tidy, see www.w3.org"> + + <title>Authentication</title> + <link rev="made" href="mailto:rbowen@rcbowen.com"> + </head> + <!-- Background white, links blue (unvisited), navy (visited), red (active) --> + + <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink= + "#000080" alink="#FF0000"> + <!--#include virtual="header.html" --> + + <h1 align="CENTER">Authentication</h1> + <a name="__index__"></a> <!-- INDEX BEGIN --> + + + <ul> + <li><a href="#introduction">Introduction</a></li> + + <li><a href="#the prerequisites">The prerequisites</a></li> + + <li><a href="#getting it working.">Getting it + working.</a></li> + + <li><a href="#letting more than one person in">Letting more + than one person in</a></li> + + <li><a href="#possible problems">Possible problems</a></li> + + <li><a href="#what other neat stuff can i do">What other neat + stuff can I do?</a></li> + + <li><a href="#more information">More information</a></li> + </ul> + <!-- INDEX END --> + <hr> + +<table border="1"> +<tr> +<td valign="top"><strong>Related Modules</strong><br> +<br> + <a href="../mod/mod_auth.html">mod_auth</a><br> + </td> +<td valign="top"><strong>Related Directives</strong><br> +<br> + <a href="../mod/mod_access.html#allow">Allow</a><br> + <a href="../mod/mod_auth.html#authgroupfile">AuthGroupFile</a><br> + <a href="../mod/core.html#authname">AuthName</a><br> + <a href="../mod/core.html#authtype">AuthType</a><br> + <a href="../mod/mod_auth.html#authuserfile">AuthUserFile</a><br> + <a href="../mod/mod_access.html#deny">Deny</a><br> + <a href="../mod/core.html#options">Options</a><br> + <a href="../mod/core.html#require">Require</a><br> + + </td> +</tr> +</table> + + + <h1><a name="authentication">Authentication</a></h1> + + <p>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.</p> + + <h2><a name="introduction">Introduction</a></h2> + + <p>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 them.</p> + + <p>This article covers the "standard" way of protecting parts of your + web site that most of you are going to use.</p> + + <h2><a name="the prerequisites">The prerequisites</a></h2> + + <p>The directives discussed in this article will need to go either + in your main server configuration file, or in per-directory + configuration files (<code>.htaccess</code> files).</p> + + <p>If you plan to use <code>.htaccess</code> files, you will need to + have a server configuration that permits putting authentication + directives in these files. This is done with the + <code><a href="../mod/core.html#allowoverride">AllowOverride</a></code> + directive, which specifies which directives, if any, may be put in + per-directory configuration files.</p> + + <p>Since we're talking here about authentication, you will need an + <code>AllowOverride</code> directive like the following:</p> + +<pre> + AllowOverride AuthConfig +</pre> + + <p>Or, if you are just going to put the directives directly in your + main server configuration file, you will of course need to have + write permission to that file.</p> + + <p>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.</p> + + <h2><a name="getting it working.">Getting it working.</a></h2> + + <p>Here's the basics of password protecting a directory on your + server.</p> + + <p>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 + <code>/usr/local/apache/htdocs</code> you might want to put the + password file(s) in <code>/usr/local/apache/passwd</code>.</p> + + <p>To create the file, use the <code>htpasswd</code> utility + that came with Apache. This be located in the <code>bin</code> + directory of wherever you installed Apache. To create the file, + type:</p> +<pre> + htpasswd -c /usr/local/apache/passwd/password rbowen +</pre> + + <p><code>htpasswd</code> will ask you for the password, and + then ask you to type it again to confirm it:</p> +<pre> + # htpasswd -c /usr/local/apache/passwd/passwords rbowen + New password: mypassword + Re-type new password: mypassword + Adding password for user rbowen +</pre> + + <p>If <code>htpasswd</code> 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 + <code>/usr/local/apache/bin/htpasswd</code></p> + + <p>Next, you'll need to create a file in the directory you want + to protect. This file is usually called <code>.htaccess</code>, + although on Windows it's called <code>htaccess</code> (without + the leading period.) <code>.htaccess</code> needs to contain + the following lines:</p> +<pre> + AuthType Basic + AuthName "By Invitation Only" + AuthUserFile /usr/local/apache/passwd/passwords + AuthGroupFile /dev/null + require user rbowen +</pre> + + <p>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 <code>.htaccess</code> files in the directory in + question.</p> + + <h2><a name="letting more than one person in">Letting more than + one person in</a></h2> + + <p>The directives above only let one person (specifically + someone with a username of <code>rbowen</code>) into the + directory. In most cases, you'll want to let more than one + person in. This is where the <code>AuthGroupFile</code> comes + in. In the example above, we've pointed + <code>AuthGroupFile</code> to <code>/dev/null</code>, which is + Unix-speak for "nowhere", or "off into space." (The Windows + NT equivalent of this is <code>nul</code>.)</p> + + <p>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:</p> +<pre> + GroupName: rbowen dpitts sungo rshersey +</pre> + + <p>That's just a list of the members of the group in a long + line separated by spaces.</p> + + <p>To add a user to your already existing password file, + type:</p> +<pre> + htpasswd /usr/local/apache/passwd/password dpitts +</pre> + + <p>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 <code>-c</code> that makes it create a new password + file.</p> + + <p>Now, you need to modify your <code>.htaccess</code> file to + look like the following:</p> +<pre> + AuthType Basic + AuthName "By Invitation Only" + AuthUserFile /usr/local/apache/passwd/passwords + AuthGroupFile /usr/local/apache/passwd/groups + require group GroupName +</pre> + + <p>Now, anyone that is listed in the group + <code>GroupName</code>, and has an entry in the + <code>password</code> file, will be let in, if they type the + correct password.</p> + + <p>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:</p> +<pre> + require valid-user +</pre> + + <p>Using that rather than the <code>require user rbowen</code> + 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 just 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 th right one in the + <code>AuthUserFile</code> directive.</p> + + <h2><a name="possible problems">Possible problems</a></h2> + + <p>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 + it has to 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.</p> + + <p>A consequence of this is that there's a practical limit to how many + users you can put in one password file. This limit will vary + depending on the performance of your particular server machine, but + you can expect to see slowdowns once you get above a few hundred + entries, and may wish to consider a different authentication method + at that time.</p> + + <h2><a name="what other neat stuff can i do">What other neat + stuff can I do?</a></h2> + + <p>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.</p> + + <p>The <code>allow</code> and <code>deny</code> 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 <code>order</code> + directive, which tells Apache in which order to apply the + filters.</p> + + <p>The usage of these directives is:</p> +<pre> + allow from address +</pre> + + <p>where <em>address</em> is an IP address (or a partial IP + address) or a fully qualified domain name (or a partial domain + name).</p> + + <p>For example, if you have someone spamming your message + board, and you want to keep them out, you could do the + following:</p> +<pre> + deny from 205.252.46.165 +</pre> + + <p>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.</p> +<pre> + deny from host.example.com +</pre> + + <p>And, if you'd like to block access from an entire domain, + you can specify just part of an address or domain name:</p> +<pre> + deny from 192.101.205 + deny from cyberthugs.com + deny from ke +</pre> + + <p>Using <code>order</code> will let you be sure that you are + actually restricting things to the group that you want to let + in, by combining a <code>deny</code> and an <code>allow</code> + directive:</p> +<pre> + order deny,allow + deny from all + allow from dev.example.com +</pre> + + <p>Listing just the <code>allow</code> 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 + <em>only</em> those folks in.</p> + + <h2><a name="more information">More information</a></h2> + + <p>You should also read the documentation for + <code><a href="../mod/mod_auth.html">mod_auth</a></code> + which contains + some more information about how this all works.</p> + </body> +</html> + |