From: Joshua Slive Date: Wed, 19 Sep 2001 15:27:17 +0000 (+0000) Subject: There is still some stuff I'd like to do here, but I'll commit what X-Git-Tag: 2.0.26~215 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=42b1ce9084e86d12568fa8b5b15119e94ba9e4b6;p=thirdparty%2Fapache%2Fhttpd.git There is still some stuff I'd like to do here, but I'll commit what I have for the moment. I've done three things: 1. Emphasize that auth does not need to be in .htaccess. 2. Add detailed discussion of each of the auth directives (does this belong here?) 3. Remove the AuthGroupFile /dev/null which shouldn't be necessary. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@91088 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/howto/auth.html b/docs/manual/howto/auth.html index 8fab3865fbc..54645a09420 100644 --- a/docs/manual/howto/auth.html +++ b/docs/manual/howto/auth.html @@ -81,8 +81,9 @@

The prerequisites

The directives discussed in this article will need to go either - in your main server configuration file, or in per-directory - configuration files (.htaccess files).

+ in your main server configuration file (typically in a + <Directory> section), or in per-directory configuration + files (.htaccess files).

If you plan to use .htaccess files, you will need to have a server configuration that permits putting authentication @@ -113,16 +114,16 @@ server.

You'll need to create a password file. This file should be - placed somewhere outside of your document directory. This is so + placed somewhere not accessible from the web. 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 file(s) in /usr/local/apache/passwd.

-

To create the file, use the htpasswd utility - that came with Apache. This be located in the bin - directory of wherever you installed Apache. To create the file, - type:

+

To create the file, use the htpasswd utility that came + with Apache. This be located in the bin directory of + wherever you installed Apache. To create the file, type:

         htpasswd -c /usr/local/apache/passwd/password rbowen
@@ -141,36 +142,87 @@ On my server, it's located at /usr/local/apache/bin/htpasswd

-

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 called htaccess (without - the leading period.) .htaccess needs to contain - the following lines:

+

Next, you'll need to configure the server to request a password + and tell the server which users are allowed access. You can do + this either by editing the httpd.conf file or using + an .htaccess file. For example, if you wish to + protect the directory + /usr/local/apache/htdocs/secret, you can use the + following directives, either placed in the file + /usr/local/apache/htdocs/secret/.htaccess, or placed + in httpd.conf inside a <Directory + /usr/local/apache/apache/htdocs/secret> section.

         AuthType Basic
-        AuthName "By Invitation Only"
+        AuthName "Restricted Files"
         AuthUserFile /usr/local/apache/passwd/passwords
-        AuthGroupFile /dev/null
         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.

+

Let's examine each of those directives individually. The AuthType directive selects + that method that is used to authenticate the user. The most + common method is Basic, and this is the method + implemented by mod_auth. It is + important to be aware, however, that Basic authentication sends + the password from the client to the browser unencrypted. This + method should therefore not be used for highly sensitive data. + Apache supports one other authentication method: AuthType + Digest. This method is implemented by mod_auth_digest and is much + more secure. Only the most recent versions of clients are known + to support Digest authentication.

+ +

The AuthName directive + sets the Realm to be used in the authentication. The + realm serves two major functions. First, the client often + presents this information to the user as part of the password + dialog box. Second, it is used by the client to determine what + password to send for a given authenticated area. So, for example, + once a client has authenticated in the "Restricted + Files" area, it will automatically retry the same password + for any area on the same server that is marked with the + "Restricted Files" Realm. Therefore, you can prevent + a user from being prompted more than once for a password by + letting multiple restricted areas share the same realm. Of + course, for security reasons, the client will always need to ask + again for the password whenever the hostname of the server + changes.

+ +

The AuthUserFile + directive sets the path to the password file that we just created + with htpasswd. If you have a large number of users, + it can be quite slow to search through a plain text file to + authenticate the user on each request. Apache also has the + ability to store user information in fast database files. The + modules mod_auth_db and mod_auth_dbm provide the AuthDBUserFile + and AuthDBMUserFile + directives respectively. These files can be created and + manipulated with the dbmmanage program. Many + other types of authentication options are available from third + party modules in the Apache + Modules Database.

+ +

Finally, the require + directive provides the authorization part of the process by + setting the user that is allowed to access this region of the + server. In the next section, we discuss various ways to + use the require directive.

Letting more than one person in

-

The directives above only let one person (specifically - someone with a username of rbowen) into the - directory. In most cases, you'll want to let more than one - person in. This is where the AuthGroupFile comes - in. In the example above, we've pointed - AuthGroupFile to /dev/null, which is - Unix-speak for "nowhere", or "off into space." (The Windows - NT equivalent of this is nul.)

+

The directives above only let one person (specifically someone + with a username of rbowen) into the directory. In + most cases, you'll want to let more than one person in. This is + where the AuthGroupFile comes + in.

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 @@ -227,7 +279,7 @@ files, and remember to reference th right one in the AuthUserFile directive.

-

Possible problems

+

Possible problems

Because of the way that Basic authentication is specified, your username and password must be verified every time you diff --git a/docs/manual/howto/auth.html.en b/docs/manual/howto/auth.html.en index 8fab3865fbc..54645a09420 100644 --- a/docs/manual/howto/auth.html.en +++ b/docs/manual/howto/auth.html.en @@ -81,8 +81,9 @@

The prerequisites

The directives discussed in this article will need to go either - in your main server configuration file, or in per-directory - configuration files (.htaccess files).

+ in your main server configuration file (typically in a + <Directory> section), or in per-directory configuration + files (.htaccess files).

If you plan to use .htaccess files, you will need to have a server configuration that permits putting authentication @@ -113,16 +114,16 @@ server.

You'll need to create a password file. This file should be - placed somewhere outside of your document directory. This is so + placed somewhere not accessible from the web. 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 file(s) in /usr/local/apache/passwd.

-

To create the file, use the htpasswd utility - that came with Apache. This be located in the bin - directory of wherever you installed Apache. To create the file, - type:

+

To create the file, use the htpasswd utility that came + with Apache. This be located in the bin directory of + wherever you installed Apache. To create the file, type:

         htpasswd -c /usr/local/apache/passwd/password rbowen
@@ -141,36 +142,87 @@ On my server, it's located at /usr/local/apache/bin/htpasswd

-

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 called htaccess (without - the leading period.) .htaccess needs to contain - the following lines:

+

Next, you'll need to configure the server to request a password + and tell the server which users are allowed access. You can do + this either by editing the httpd.conf file or using + an .htaccess file. For example, if you wish to + protect the directory + /usr/local/apache/htdocs/secret, you can use the + following directives, either placed in the file + /usr/local/apache/htdocs/secret/.htaccess, or placed + in httpd.conf inside a <Directory + /usr/local/apache/apache/htdocs/secret> section.

         AuthType Basic
-        AuthName "By Invitation Only"
+        AuthName "Restricted Files"
         AuthUserFile /usr/local/apache/passwd/passwords
-        AuthGroupFile /dev/null
         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.

+

Let's examine each of those directives individually. The AuthType directive selects + that method that is used to authenticate the user. The most + common method is Basic, and this is the method + implemented by mod_auth. It is + important to be aware, however, that Basic authentication sends + the password from the client to the browser unencrypted. This + method should therefore not be used for highly sensitive data. + Apache supports one other authentication method: AuthType + Digest. This method is implemented by mod_auth_digest and is much + more secure. Only the most recent versions of clients are known + to support Digest authentication.

+ +

The AuthName directive + sets the Realm to be used in the authentication. The + realm serves two major functions. First, the client often + presents this information to the user as part of the password + dialog box. Second, it is used by the client to determine what + password to send for a given authenticated area. So, for example, + once a client has authenticated in the "Restricted + Files" area, it will automatically retry the same password + for any area on the same server that is marked with the + "Restricted Files" Realm. Therefore, you can prevent + a user from being prompted more than once for a password by + letting multiple restricted areas share the same realm. Of + course, for security reasons, the client will always need to ask + again for the password whenever the hostname of the server + changes.

+ +

The AuthUserFile + directive sets the path to the password file that we just created + with htpasswd. If you have a large number of users, + it can be quite slow to search through a plain text file to + authenticate the user on each request. Apache also has the + ability to store user information in fast database files. The + modules mod_auth_db and mod_auth_dbm provide the AuthDBUserFile + and AuthDBMUserFile + directives respectively. These files can be created and + manipulated with the dbmmanage program. Many + other types of authentication options are available from third + party modules in the Apache + Modules Database.

+ +

Finally, the require + directive provides the authorization part of the process by + setting the user that is allowed to access this region of the + server. In the next section, we discuss various ways to + use the require directive.

Letting more than one person in

-

The directives above only let one person (specifically - someone with a username of rbowen) into the - directory. In most cases, you'll want to let more than one - person in. This is where the AuthGroupFile comes - in. In the example above, we've pointed - AuthGroupFile to /dev/null, which is - Unix-speak for "nowhere", or "off into space." (The Windows - NT equivalent of this is nul.)

+

The directives above only let one person (specifically someone + with a username of rbowen) into the directory. In + most cases, you'll want to let more than one person in. This is + where the AuthGroupFile comes + in.

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 @@ -227,7 +279,7 @@ files, and remember to reference th right one in the AuthUserFile directive.

-

Possible problems

+

Possible problems

Because of the way that Basic authentication is specified, your username and password must be verified every time you