From f3ceda796970611522c38e4b96e60375768aa9b5 Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Wed, 5 Sep 2001 01:40:17 +0000 Subject: [PATCH] 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 --- docs/manual/howto/auth.html | 318 +++++++++++++++++++++++++++++++++ docs/manual/howto/auth.html.en | 318 +++++++++++++++++++++++++++++++++ 2 files changed, 636 insertions(+) create mode 100644 docs/manual/howto/auth.html create mode 100644 docs/manual/howto/auth.html.en diff --git a/docs/manual/howto/auth.html b/docs/manual/howto/auth.html new file mode 100644 index 0000000000..9311ffcf81 --- /dev/null +++ b/docs/manual/howto/auth.html @@ -0,0 +1,318 @@ + + + + + + + Authentication + + + + + + + +

Authentication

+ + + + + +
+ + + + + + +
Related Modules
+
+ mod_auth
+ 		Related Directives
+
+ Allow
+ AuthGroupFile
+ AuthName
+ AuthType
+ AuthUserFile
+ Deny
+ Options
+ Require
+ +
+ + +

Authentication

+ +

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.

+ +

Introduction

+ +

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.

+ +

This article covers the "standard" way of protecting parts of your + web site that most of you are going to use.

+ +

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).

+ +

If you plan to use .htaccess files, you will need to + have a server configuration that permits putting authentication + directives in these files. This is done with the + AllowOverride + directive, which specifies which directives, if any, may be put in + per-directory configuration files.

+ +

Since we're talking here about authentication, you will need an + AllowOverride directive like the following:

+ +
+    AllowOverride AuthConfig
+
+ +

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.

+ +

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.

+ +

Getting it working.

+ +

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 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:

+
+        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
+
+ +

If 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 + /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:

+
+        AuthType Basic
+        AuthName "By Invitation Only"
+        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.

+ +

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.)

+ +

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 spaces.

+ +

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 -c that makes it create a new password + file.

+ +

Now, you need to modify your .htaccess file to + look like the following:

+
+        AuthType Basic
+        AuthName "By Invitation Only"
+        AuthUserFile /usr/local/apache/passwd/passwords
+        AuthGroupFile /usr/local/apache/passwd/groups
+        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 + correct password.

+ +

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:

+
+        require valid-user
+
+ +

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 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 + AuthUserFile directive.

+ +

Possible problems

+ +

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.

+ +

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.

+ +

What other neat + stuff can I do?

+ +

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.

+ +

The allow and 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 + filters.

+ +

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 205.252.46.165
+
+ +

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 host.example.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
+
+ +

Using 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 allow + directive:

+
+        order deny,allow
+        deny from all
+        allow from dev.example.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.

+ +

More information

+ +

You should also read the documentation for + mod_auth + which contains + some more information about how this all works.

+ + + 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 @@ + + + + + + + Authentication + + + + + + + +

Authentication

+ + + + + +
+ + + + + + +
Related Modules
+
+ mod_auth
+ 		Related Directives
+
+ Allow
+ AuthGroupFile
+ AuthName
+ AuthType
+ AuthUserFile
+ Deny
+ Options
+ Require
+ +
+ + +

Authentication

+ +

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.

+ +

Introduction

+ +

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.

+ +

This article covers the "standard" way of protecting parts of your + web site that most of you are going to use.

+ +

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).

+ +

If you plan to use .htaccess files, you will need to + have a server configuration that permits putting authentication + directives in these files. This is done with the + AllowOverride + directive, which specifies which directives, if any, may be put in + per-directory configuration files.

+ +

Since we're talking here about authentication, you will need an + AllowOverride directive like the following:

+ +
+    AllowOverride AuthConfig
+
+ +

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.

+ +

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.

+ +

Getting it working.

+ +

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 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:

+
+        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
+
+ +

If 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 + /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:

+
+        AuthType Basic
+        AuthName "By Invitation Only"
+        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.

+ +

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.)

+ +

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 spaces.

+ +

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 -c that makes it create a new password + file.

+ +

Now, you need to modify your .htaccess file to + look like the following:

+
+        AuthType Basic
+        AuthName "By Invitation Only"
+        AuthUserFile /usr/local/apache/passwd/passwords
+        AuthGroupFile /usr/local/apache/passwd/groups
+        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 + correct password.

+ +

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:

+
+        require valid-user
+
+ +

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 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 + AuthUserFile directive.

+ +

Possible problems

+ +

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.

+ +

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.

+ +

What other neat + stuff can I do?

+ +

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.

+ +

The allow and 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 + filters.

+ +

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 205.252.46.165
+
+ +

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 host.example.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
+
+ +

Using 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 allow + directive:

+
+        order deny,allow
+        deny from all
+        allow from dev.example.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.

+ +

More information

+ +

You should also read the documentation for + mod_auth + which contains + some more information about how this all works.

+ + + -- 2.40.0