From: Andre Malo Date: Mon, 9 Dec 2002 22:19:13 +0000 (+0000) Subject: full clean-up of the auth-docs; feel free to shake out any X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6e99588f568eed2571842778818a4936d81d9ff2;p=apache full clean-up of the auth-docs; feel free to shake out any nits, if there are (probably there *are* :) main changes: - introduce docs for mod_authn_default, mod_authz_default and mod_authz_user - fix argument lists of the provider directives - fix the examples (intended to be better :) - introduce the AuthDigestShmemSize directive - remove AuthDigestUser/GroupFile - mention htdigest in AuthUserFile docs - mod_authn_anon is now an authn provider - markup Reviewed by: Astrid Ke�ler git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@97823 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_auth_basic.xml b/docs/manual/mod/mod_auth_basic.xml index 0c3cb2fde2..677019d7f5 100644 --- a/docs/manual/mod/mod_auth_basic.xml +++ b/docs/manual/mod/mod_auth_basic.xml @@ -11,12 +11,10 @@ Available in Apache 2.1 and later -

This module allows the use of HTTP Basic Authentication to restrict access by looking up users in the given providers. HTTP Digest Authentication is provided by mod_auth_digest.

- AuthName AuthType @@ -24,43 +22,55 @@ AuthBasicProvider Sets the authentication provider(s) for this location -AuthBasicProvider provider-name - - directory - .htaccess - -AuthConfig +AuthBasicProvider On|Off|provider-name +[provider-name] ... +AuthBasicProvider On +directory

The AuthBasicProvider directive sets - which provider is used to authenticate the users for this location.

+ which provider is used to authenticate the users for this location. + Setting the value to On will choose the default provider + (file). Since the file provider is implemented + by the mod_authn_file module, you have to make sure, + that the module is present in the server.

+ + Example + <Location /secure>
+ + AuthBasicProvider dbm
+ AuthDBMType SDBM
+ AuthDBMUserFile /www/etc/dbmpasswd
+ Require valid-user
+ + </Location> + -

See mod_authn_dbm, mod_authn_file +

See mod_authn_dbm and mod_authn_file for providers.

+

The value Off clears the provider list and sets it back + to the default.

 AuthBasicAuthoritative -Sets whether authorization and authentication are -passed to lower level modules -AuthBasicAuthoritative on|off -AuthBasicAuthoritative on - - directory - .htaccess +Sets whether authorization and authentication are passed to +lower level modules +AuthBasicAuthoritative On|Off +AuthBasicAuthoritative On +directory.htaccess AuthConfig

Setting the AuthBasicAuthoritative directive - explicitly to 'off' allows for both + explicitly to Off allows for both authentication and authorization to be passed on to lower level - modules (as defined in the Configuration and - modules.c files) if there is no - userID or rule matching the supplied - userID. If there is a userID and/or rule specified; the usual + modules (as defined in the modules.c files) if there is + no userID or rule matching the + supplied userID. If there is a userID and/or rule specified, the usual password and access checks will be applied and a failure will give an Authorization Required reply.

@@ -70,11 +80,10 @@ passed to lower level modules will verify the credentials; and no access is passed on; regardless of the AuthAuthoritative setting.

-

By default; control is not passed on; and an unknown userID or +

By default control is not passed on and an unknown userID or rule will result in an Authorization Required reply. Not setting - it thus keeps the system secure; and forces an NCSA compliant + it thus keeps the system secure and forces an NCSA compliant behaviour.

- diff --git a/docs/manual/mod/mod_auth_digest.xml b/docs/manual/mod/mod_auth_digest.xml index dfe15f496d..4709d94b3c 100644 --- a/docs/manual/mod/mod_auth_digest.xml +++ b/docs/manual/mod/mod_auth_digest.xml @@ -11,7 +11,7 @@ auth_digest_module -

This module implements HTTP Digest Authentication. However, it +

This module implements HTTP Digest Authentication. However, it has not been extensively tested and is therefore marked experimental.

 @@ -24,20 +24,26 @@
Using Digest Authentication

Using MD5 Digest authentication is very simple. Simply set - up authentication normally, using "AuthType Digest" and - "AuthDigestFile" instead of the normal "AuthType Basic" and - "AuthUserFile"; also, replace any "AuthGroupFile" with - "AuthDigestGroupFile". Then add a "AuthDigestDomain" directive - containing at least the root URI(s) for this protection space. - Example:

- - + up authentication normally, using AuthType Digest and + AuthDigestProvider + instead of the normal AuthType Basic and + AuthBasicProvider. + Then add a AuthDigestDomain directive containing at least the root + URI(s) for this protection space.

+ +

Appropriate user (text) files can be created using the + htdigest tool.

+ + Example: <Location /private/>
AuthType Digest
AuthName "private area"
AuthDigestDomain /private/ http://mirror.my.dom/private2/
- AuthDigestFile /web/auth/.digest_pw
+
+ AuthDigestProvider file
+ AuthUserFile /web/auth/.digest_pw
Require valid-user
 </Location> @@ -46,67 +52,40 @@ Note

Digest authentication provides a more secure password system than Basic authentication, but only works with supporting - browsers. As of July 2002, the major browsers that support digest + browsers. As of November 2002, the major browsers that support digest authentication are Opera, MS Internet Explorer (fails when used with a query string), Amaya and Mozilla. Since digest + href="http://www.w3.org/Amaya/">Amaya, Mozilla and Netscape since version 7. Since digest authentication is not as widely implemented as basic - authentication, you should use it only in controlled settings.

+ authentication, you should use it only in controlled environments.
-AuthDigestFile -Location of the text file containing the list -of users and encoded passwords for digest authentication -AuthDigestFile file-path -directory.htaccess - -AuthConfig +AuthDigestProvider +Sets the authentication provider(s) for this location +AuthDigestProvider On|Off|provider-name +[provider-name] ... +AuthBasicProvider On +directory -

The AuthDigestFile directive sets the - name of a textual file containing the list of users and encoded - passwords for digest authentication. File-path is the - absolute path to the user file.

- -

The digest file uses a special format. Files in this format - can be created using the htdigest utility found in - the support/ subdirectory of the Apache distribution.

- - - - -AuthDigestGroupFile -Name of the text file containing the list of groups -for digest authentication -AuthDigestGroupFile file-path -directory.htaccess - -AuthConfig - - -

The AuthDigestGroupFile directive sets - the name of a textual file containing the list of groups and their - members (user names). File-path is the absolute path to - the group file.

- -

Each line of the group file contains a groupname followed by - a colon, followed by the member usernames separated by spaces. - Example:

- - mygroup: bob joe anne - -

Note that searching large text files is very - inefficient.

- -

Security: make sure that the AuthGroupFile is stored outside - the document tree of the web-server; do not put it in - the directory that it protects. Otherwise, clients will be able - to download the AuthGroupFile.

+

The AuthDigestProvider directive sets + which provider is used to authenticate the users for this location. + Setting the value to On will choose the default provider + (file). Since the file provider is implemented + by the mod_authn_file module, you have to make sure, + that the module is present in the server.

+ +

See mod_authn_dbm and mod_authn_file + for providers.

+ +

The value Off clears the provider list and sets it back + to the default.

 @@ -122,8 +101,8 @@ authentication

The AuthDigestQop directive determines - the quality-of-protection to use. auth will only do - authentication (username/password); auth-int is + the quality-of-protection to use. auth will + only do authentication (username/password); auth-int is authentication plus integrity checking (an MD5 hash of the entity is also computed and checked); none will cause the module to use the old RFC-2069 digest algorithm (which does not include @@ -155,7 +134,7 @@ authentication greater than 0 then it specifies the amount of time for which the nonce is valid; this should probably never be set to less than 10 seconds. If seconds is less than 0 then the nonce never - expires. -

+ Not implemented yet. + @@ -202,16 +179,16 @@ server Not implemented yet. @@ -235,8 +212,9 @@ response hases in digest authentication MD5-sess is not correctly implemented yet. @@ -274,4 +252,36 @@ authentication + +AuthDigestShmemSize +The amount of shared memory to allocate for keeping track +of clients +AuthDigestShmemSize size +AuthDigestShmemSize 1000 +server config + + +

The AuthDigestShmemSize directive defines + the amount of shared memory, that will be allocated at the server + startup for keeping track of clients. Note that the shared memory + segment cannot be set less than the space that is neccessary for + tracking at least one client. This value is dependant on your + system. If you want to find out the exact value, you may simply + set AuthDigestShmemSize to the value of + 0 and read the error message after trying to start the + server.

+ +

The size is normally expressed in Bytes, but you + may let the number follow a K or an M to + express your value as KBytes or MBytes. For example, the following + directives are all equivalent:

+ + + AuthDigestShmemSize 1048576
+ AuthDigestShmemSize 1024K
+ AuthDigestShmemSize 1M
+ + + + diff --git a/docs/manual/mod/mod_authn_anon.xml b/docs/manual/mod/mod_authn_anon.xml index ef87db96a4..29b13d32ee 100644 --- a/docs/manual/mod/mod_authn_anon.xml +++ b/docs/manual/mod/mod_authn_anon.xml @@ -12,8 +12,9 @@ Available in Apache 2.1 and later -

This module does access control in a manner similar to - anonymous-ftp sites; i.e. have a 'magic' user id +

This module provides authentication front-ends such as + mod_auth_basic to authenticate users similar + to anonymous-ftp sites, i.e. have a 'magic' user id 'anonymous' and the email address as a password. These email addresses can be logged.

@@ -24,25 +25,30 @@ tracking is that, unlike magic-cookies and funny URL pre/postfixes, it is completely browser independent and it allows users to share URLs.

- -
Example +

When using mod_auth_basic, this module is invoked + via the AuthBasicProvider + directive with the anon value.

+ -

The example below (when combined with the Auth directives of a - htpasswd-file based (or GDM, mSQL etc.) base access - control system allows users in as 'guests' with the following - properties:

+
Example +

The example below is combined with "normal" htpasswd-file based + authentication and allows users in additionally as 'guests' with the + following properties:

  • It insists that the user enters a userId. - (Anonymous_NoUserId)
    • + (Anonymous_NoUserId)
  • It insists that the user enters a password. - (Anonymous_MustGiveEmail)
    • + (Anonymous_MustGiveEmail) -
  • The password entered must be a valid email address, ie. +
  • The password entered must be a valid email address, i.e. contain at least one '@' and a '.'. - (Anonymous_VerifyEmail)
    • + (Anonymous_VerifyEmail)
  • The userID must be one of anonymous guest www test welcome and comparison is not case @@ -50,41 +56,38 @@
  • And the Email addresses entered in the passwd field are logged to the error log file - (Anonymous_LogEmail)
    • + (Anonymous_LogEmail)
-

Excerpt of httpd.conf:

- - - Anonymous_NoUserId off
- Anonymous_MustGiveEmail on
- Anonymous_VerifyEmail on
- Anonymous_LogEmail on
- Anonymous anonymous guest www test welcome
-
- AuthName "Use 'anonymous' & Email address for - guest entry"
- AuthType basic
-
- # An - AuthUserFile/AuthDBMUserFile
- # directive must be specified, or use
- # Anonymous_Authoritative for public access.
- # In the .htaccess for the public directory, add:
- <Files *>
- Order Deny,Allow
- Allow from all
-
- Require valid-user
- </Files>
- + Example + <Directory /foo> + + AuthName "Use 'anonymous' & Email address for guest entry"
+ AuthType Basic
+ AuthBasicProvider file anon
+ AuthUserFile /path/to/your/.htpasswd
+
+ Anonymous_NoUserId off
+ Anonymous_MustGiveEmail on
+ Anonymous_VerifyEmail on
+ Anonymous_LogEmail on
+ Anonymous anonymous guest www test welcome
+
+ Order Deny,Allow
+ Allow from all
+
+ Require valid-user
+ + </Directory> +
Anonymous Specifies userIDs that areallowed access without password verification -Anonymous user [user] ... +Anonymous user [user] ... directory.htaccess AuthConfig @@ -97,39 +100,17 @@ password verification

Please note that the comparison is case-IN-sensitive.
- I strongly suggest that the magic username + It's strongly recommended that the magic username 'anonymous' is always one of the allowed userIDs.

-

Example:

-Anonymous anonymous "Not Registered" 'I don\'t know' + Example: + Anonymous anonymous "Not Registered" "I don't know" +

This would allow the user to enter without password - verification by using the userId's 'anonymous', - 'AnonyMous','Not Registered' and 'I Don't Know'.

- - - - -Anonymous_Authoritative -Configures if authorization will fall-through -to other methods -Anonymous_Authoritative on|off -Anonymous_Authoritative off -directory.htaccess - -AuthConfig - - -

When set 'on', there is no fall-through to other authorization - methods. So if a userID does not match the values specified in the - Anonymous directive, - access is denied.

- -

Be sure you know what you are doing when you decide to - switch it on. And remember that it is the linking order of the - modules (in the Configuration / Make file) which details the - order in which the Authorization modules are queried.

+ verification by using the userIDs "anonymous", + "AnonyMous", "Not Registered" and "I Don't Know".

 @@ -137,14 +118,14 @@ to other methods Anonymous_LogEmail Sets whether the password entered will be logged in the error log -Anonymous_LogEmail on|off -Anonymous_LogEmail on +Anonymous_LogEmail On|Off +Anonymous_LogEmail On directory.htaccess AuthConfig -

When set on, the default, the 'password' entered +

When set On, the default, the 'password' entered (which hopefully contains a sensible email address) is logged in the error log.

 @@ -153,8 +134,8 @@ error log Anonymous_MustGiveEmail Specifies whether blank passwords are allowed -Anonymous_MustGiveEmail on|off -Anonymous_MustGiveEmail on +Anonymous_MustGiveEmail On|Off +Anonymous_MustGiveEmail On directory.htaccess AuthConfig @@ -168,14 +149,14 @@ error log Anonymous_NoUserID Sets whether the userID field may be empty -Anonymous_NoUserID on|off -Anonymous_NoUserID off +Anonymous_NoUserID On|Off +Anonymous_NoUserID Off directory.htaccess AuthConfig -

When set on, users can leave the userID (and +

When set On, users can leave the userID (and perhaps the password field) empty. This can be very convenient for MS-Explorer users who can just hit return or click directly on the OK button; which seems a natural reaction.

@@ -186,17 +167,17 @@ error log Anonymous_VerifyEmail Sets whether to check the password field for a correctly formatted email address -Anonymous_VerifyEmail on|off -Anonymous_VerifyEmail off +Anonymous_VerifyEmail On|Off +Anonymous_VerifyEmail Off directory.htaccess AuthConfig -

When set on the 'password' entered is checked for +

When set On the 'password' entered is checked for at least one '@' and a '.' to encourage users to enter valid email addresses (see the above Auth_LogEmail).

+ module="mod_authn_anon">Anonymous_LogEmail).

 diff --git a/docs/manual/mod/mod_authn_dbm.xml b/docs/manual/mod/mod_authn_dbm.xml index b08d3742b3..f79b615a3c 100644 --- a/docs/manual/mod/mod_authn_dbm.xml +++ b/docs/manual/mod/mod_authn_dbm.xml @@ -13,14 +13,15 @@

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic - to authenticate users by looking up users in plain text password files. - Similar functionality is provided by mod_authn_file.

+ to authenticate users by looking up users in dbm password + files. Similar functionality is provided by + mod_authn_file.

When using mod_auth_basic or mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider - with the 'dbm' value.

+ with the dbm value.

 AuthName @@ -36,17 +37,15 @@ AuthDBMUserFile Sets the name of a database file containing the list of users and passwords for authentication -AuthDBMUserFile file-path - - directory - .htaccess +AuthDBMUserFile file-path +directory.htaccess AuthConfig

The AuthDBMUserFile directive sets the name of a DBM file containing the list of users and passwords for - user authentication. File-path is the absolute path to + user authentication. File-path is the absolute path to the user file.

The user file is keyed on the username. The value for a user is @@ -61,8 +60,8 @@ passwords for authentication download the AuthDBMUserFile.

Important compatibility note: The implementation of - "dbmopen" in the apache modules reads the string length of the - hashed values from the DBM data structures, rather than relying + dbmopen in the apache modules reads the string length of + the hashed values from the DBM data structures, rather than relying upon the string being NULL-appended. Some applications, such as the Netscape web server, rely upon the string being NULL-appended, so if you are having trouble using DBM files @@ -82,22 +81,18 @@ passwords for authentication store passwords AuthDBMType default|SDBM|GDBM|NDBM|DB AuthDBMType default - - directory - .htaccess +directory.htaccess AuthConfig -Available in version 2.0.30 and later. +

Sets the type of database file that is used to store the passwords. + The default database type is determined at compile time. The + availability of other types of database files also depends on + compile-time settings.

-

Sets the type of database file that is used to store the passwords. -The default database type is determined at compile time. The -availability of other types of database files also depends on -compile-time settings.

- -

It is crucial that whatever program you use to create your password -files is configured to use the same type of database.

+

It is crucial that whatever program you use to create your password + files is configured to use the same type of database.

 diff --git a/docs/manual/mod/mod_authn_default.xml b/docs/manual/mod/mod_authn_default.xml new file mode 100644 index 0000000000..9b8f544df5 --- /dev/null +++ b/docs/manual/mod/mod_authn_default.xml @@ -0,0 +1,46 @@ + + + + + +mod_authn_default +Authentication fallback module +Base +mod_authn_default.c +authn_default_module +Available in Apache 2.1 and later + + +

This module is designed to be the fallback module, if you don't + have configured an authentication module like + mod_auth_basic. It simply rejects any + credentials supplied by the user.

+ + + +AuthDefaultAuthoritative +Sets whether authentication is passed to lower level +modules +AuthDefaultAuthoritative On|Off +AuthDefaultAuthoritative On +directory.htaccess + +AuthConfig + + +

Setting the AuthDefaultAuthoritative directive + explicitly to Off allows for authentication to be passed on + to lower level modules (as defined in the modules.c + files).

+ + Note +

Normally there are no lower level modules, since + mod_authn_default is defined to be already on + a very low level. Therefore you should leave the value of + AuthDefaultAuthoritative as default + (On).

+ + + + + diff --git a/docs/manual/mod/mod_authn_file.xml b/docs/manual/mod/mod_authn_file.xml index ffa70f60d3..725231d399 100644 --- a/docs/manual/mod/mod_authn_file.xml +++ b/docs/manual/mod/mod_authn_file.xml @@ -11,7 +11,6 @@ Available in Apache 2.1 and later -

This module provides authentication front-ends such as mod_auth_digest and mod_auth_basic to authenticate users by looking up users in plain text password files. @@ -21,65 +20,77 @@ mod_auth_digest, this module is invoked via the AuthBasicProvider or AuthDigestProvider - with the 'file' value.

- + with the file value.

 -AuthName -AuthType AuthBasicProvider AuthDigestProvider +htpasswd +htdigest AuthUserFile Sets the name of a text file containing the list of users and passwords for authentication -AuthUserFile file-path - - directory - .htaccess +AuthUserFile file-path +directory.htaccess AuthConfig

The AuthUserFile directive sets the name of a textual file containing the list of users and passwords for - user authentication. File-path is the path to the user - file. If it is not absolute (i.e., if it doesn't begin - with a slash), it is treated as relative to the ServerRoot.

+ user authentication. File-path is the path to the user + file. If it is not absolute, it is treated as relative to the + ServerRoot.

Each line of the user file contains a username followed by - a colon, followed by the crypt() encrypted - password. The behavior of multiple occurrences of the same user is - undefined.

+ a colon, followed by the encrypted password. If the same user + ID is defined multiple times, mod_authn_file will + use the first occurrence to verify the password.

The utility htpasswd which is installed as part of the binary distribution, or which can be found in src/support, is used to maintain - this password file. See the man page for more - details. In short:

+ the password file for HTTP Basic Authentication. See the + man page for more details. + In short:

+ +

Create a password file Filename with + username as the initial ID. It will prompt for + the password:

-

Create a password file 'Filename' with 'username' as the - initial ID. It will prompt for the password:

- htpasswd -c Filename username + + htpasswd -c Filename username + -

Add or modify 'username2' in the password file 'Filename':

- htpasswd Filename username2 +

Add or modify username2 in the password file + Filename:

+ + + htpasswd Filename username2 +

Note that searching large text files is very inefficient; AuthDBMUserFile should be used instead.

- Security -

Make sure that the AuthUserFile is - stored outside the document tree of the web-server; do not - put it in the directory that it protects. Otherwise, clients will - be able to download the AuthUserFile.

+

If you are using HTTP Digest Authentication, the htpasswd tool is not sufficient. + You have to use htdigest + instead. Note that you cannot mix user data for Digest Authentication + and Basic Authentication within the same file.

+ + Security +

Make sure that the AuthUserFile is + stored outside the document tree of the web-server. Do + not put it in the directory that it protects. + Otherwise, clients may be able to download the + AuthUserFile.

 diff --git a/docs/manual/mod/mod_authz_dbm.xml b/docs/manual/mod/mod_authz_dbm.xml index c9de98fef7..b654b7a6d2 100644 --- a/docs/manual/mod/mod_authz_dbm.xml +++ b/docs/manual/mod/mod_authz_dbm.xml @@ -24,7 +24,7 @@ AuthDBMGroupFile Sets the name of the database file containing the list of user groups for authentication -AuthDBMGroupFile file-path +AuthDBMGroupFile file-path directory.htaccess AuthConfig @@ -32,7 +32,7 @@ of user groups for authentication

The AuthDBMGroupFile directive sets the name of a DBM file containing the list of user groups for user - authentication. File-path is the absolute path to the + authentication. File-path is the absolute path to the group file.

The group file is keyed on the username. The value for a @@ -40,12 +40,14 @@ of user groups for authentication belongs. There must be no whitespace within the value, and it must never contain any colons.

-

Security: make sure that the - AuthDBMGroupFile is stored outside the - document tree of the web-server; do not put it in the - directory that it protects. Otherwise, clients will be able to - download the AuthDBMGroupFile unless - otherwise protected.

+ Security +

Make sure that the AuthDBMGroupFile is + stored outside the document tree of the web-server. Do + not put it in the directory that it protects. + Otherwise, clients will be able to download the + AuthDBMGroupFile unless otherwise + protected.

+

Combining Group and Password DBM files: In some cases it is easier to manage a single database which contains both the @@ -55,18 +57,19 @@ of user groups for authentication accomplished by first setting the group and password files to point to the same DBM:

- -AuthDBMGroupFile /www/userbase
-AuthDBMUserFile /www/userbase - + + AuthDBMGroupFile /www/userbase
+ AuthDBMUserFile /www/userbase +

The key for the single DBM is the username. The value consists of

-Unix Crypt-ed Password : List of Groups [ : (ignored) - ] + + Encrypted Password : List of Groups [ : (ignored) ] + -

The password section contains the Unix crypt() +

The password section contains the encrypted password as before. This is followed by a colon and the comma separated list of groups. Other data may optionally be left in the DBM file after another colon; it is ignored by the authentication @@ -81,47 +84,39 @@ AuthDBMUserFile /www/userbase store passwords AuthzDBMType default|SDBM|GDBM|NDBM|DB AuthzDBMType default - - directory - .htaccess +directory.htaccess AuthConfig -Available in version 2.0.30 and later. +

Sets the type of database file that is used to store the passwords. + The default database type is determined at compile time. The + availability of other types of database files also depends on + compile-time settings.

-

Sets the type of database file that is used to store the passwords. -The default database type is determined at compile time. The -availability of other types of database files also depends on -compile-time settings.

- -

It is crucial that whatever program you use to create your password -files is configured to use the same type of database.

+

It is crucial that whatever program you use to create your password + files is configured to use the same type of database.

 AuthzDBMAuthoritative -Sets whether authorization will be passed on to lower level modules -AuthzDBMAuthoritative on|off -AuthzDBMAuthoritative on - - directory - .htaccess +Sets whether authorization will be passed on to lower level +modules +AuthzDBMAuthoritative On|Off +AuthzDBMAuthoritative On +directory.htaccess AuthConfig -

Setting the AuthzDBMAuthoritative - directive explicitly to 'off' allows for both - authentication and authorization to be passed on to lower level - modules (as defined in the Configuration and - modules.c file if there is no userID - or rule matching the supplied userID. If there is - a userID and/or rule specified; the usual password and access - checks will be applied and a failure will give an Authorization - Required reply.

+ directive explicitly to Off allows group authorization + to be passed on to lower level modules (as defined in the + modules.c file) if there is no group found + for the the supplied userID. If there are any groups + specified, the usual checks will be applied and a failure will + give an Authentication Required reply.

So if a userID appears in the database of more than one module; or if a valid Require @@ -130,21 +125,24 @@ files is configured to use the same type of database.

regardless of the AuthAuthoritative setting.

A common use for this is in conjunction with one of the - auth providers; such as mod_authn_file. Whereas this - DBM module supplies the bulk of the user credential checking; a - few (administrator) related accesses fall through to a lower - level with a well protected .htpasswd file.

- -

By default, control is not passed on and an unknown userID - or rule will result in an Authorization Required reply. Not + auth providers; such as mod_authn_dbm or + mod_authn_file. Whereas this DBM module supplies + the bulk of the user credential checking; a few (administrator) related + accesses fall through to a lower level with a well protected + .htpasswd file.

+ +

By default, control is not passed on and an unknown group + will result in an Authentication Required reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

-

Security: Do consider the implications of allowing a user to - allow fall-through in his .htaccess file; and verify that this - is really what you want; Generally it is easier to just secure - a single .htpasswd file, than it is to secure a database which - might have more access interfaces.

+ Security +

Do consider the implications of allowing a user to + allow fall-through in his .htaccess file; and verify that this + is really what you want; Generally it is easier to just secure + a single .htpasswd file, than it is to secure a + database which might have more access interfaces.

+ diff --git a/docs/manual/mod/mod_authz_default.xml b/docs/manual/mod/mod_authz_default.xml new file mode 100644 index 0000000000..081e744207 --- /dev/null +++ b/docs/manual/mod/mod_authz_default.xml @@ -0,0 +1,46 @@ + + + + + +mod_authz_default +Authorization fallback module +Base +mod_authz_default.c +authz_default_module +Available in Apache 2.1 and later + + +

This module is designed to be the fallback module, if you don't + have configured an authorization module like + mod_authz_user or mod_authz_groupfile. + It simply rejects any authorization request.

+ + + +AuthzDefaultAuthoritative +Sets whether authorization is passed to lower level +modules +AuthzDefaultAuthoritative On|Off +AuthzDefaultAuthoritative On +directory.htaccess + +AuthConfig + + +

Setting the AuthzDefaultAuthoritative directive + explicitly to Off allows for authorization to be passed on + to lower level modules (as defined in the modules.c + files).

+ + Note +

Normally there are no lower level modules, since + mod_authz_default is defined to be already on + a very low level. Therefore you should leave the value of + AuthzDefaultAuthoritative as default + (On).

+ + + + + diff --git a/docs/manual/mod/mod_authz_groupfile.xml b/docs/manual/mod/mod_authz_groupfile.xml index bbbc455b2e..1d643db781 100644 --- a/docs/manual/mod/mod_authz_groupfile.xml +++ b/docs/manual/mod/mod_authz_groupfile.xml @@ -5,16 +5,16 @@ mod_authz_groupfile Group authorization using plaintext files -Extension +Base mod_authz_groupfile.c authz_groupfile_module Available in Apache 2.1 and later

This module provides authorization capabilities so that - authenticated users can be allowed or denied access to portions - of the web site by group membership. Similar functionality is - provided by mod_authz_dbm.

+ authenticated users can be allowed or denied access to portions + of the web site by group membership. Similar functionality is + provided by mod_authz_dbm.

 Require @@ -24,79 +24,67 @@ AuthGroupFile Sets the name of a text file containing the list of user groups for authentication -AuthGroupFile file-path - - directory - .htaccess +AuthGroupFile file-path +directory.htaccess AuthConfig

The AuthGroupFile directive sets the name of a textual file containing the list of user groups for user - authentication. File-path is the path to the group - file. If it is not absolute (i.e., if it doesn't begin - with a slash), it is treated as relative to the File-path is the path to the group + file. If it is not absolute, it is treated as relative to the ServerRoot.

Each line of the group file contains a groupname followed by a - colon, followed by the member usernames separated by spaces. - Example:

+ colon, followed by the member usernames separated by spaces.

- mygroup: bob joe anne + Example: + mygroup: bob joe anne +

Note that searching large text files is very - inefficient; AuthDBMGroupFile should be used - instead.

- - Security -

Make sure that the AuthGroupFile is - stored outside the document tree of the web-server; do not - put it in the directory that it protects. Otherwise, clients will - be able to download the AuthGroupFile.

+ inefficient; AuthDBMGroupFile provides a much better performance.

+ + Security +

Make sure that the AuthGroupFile is + stored outside the document tree of the web-server; do not + put it in the directory that it protects. Otherwise, clients may + be able to download the AuthGroupFile.

 AuthzGroupFileAuthoritative -Sets whether authorization will be passed on to lower level modules -AuthzGroupFileAuthoritative on|off -AuthzGroupFileAuthoritative on - - directory - .htaccess +Sets whether authorization will be passed on to lower level +modules +AuthzGroupFileAuthoritative On|Off +AuthzGroupFileAuthoritative On +directory.htaccess AuthConfig -

Setting the AuthzGroupFileAuthoritative - directive explicitly to 'off' allows for - authorization to be passed on to lower level modules (as defined in - the Configuration and modules.c file if - there is no userID or rule matching - the supplied userID. If there is a userID and/or rule specified; the - usual password and access checks will be applied and a failure will - give an Authorization Required reply.

+ directive explicitly to Off allows for + group authorization to be passed on to lower level modules (as defined + in the modules.c files) if there is no + group matching the supplied userID.

-

So if a valid Require - directive applies to more than one module; then the first module - will verify the credentials; and no access is passed on; - regardless of the AuthzGroupFileAuthoritative - setting.

- -

By default, control is not passed on and an unknown userID - or rule will result in an Authorization Required reply. Not +

By default, control is not passed on and an unknown group + will result in an Authentication Required reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

-

Security: Do consider the implications of allowing a user to - allow fall-through in his .htaccess file; and verify that this - is really what you want; Generally it is easier to just secure - a single .htpasswd file, than it is to secure a database which - might have more access interfaces.

+ Security +

Do consider the implications of allowing a user to + allow fall-through in his .htaccess file; and verify + that this is really what you want; Generally it is easier to just + secure a single .htpasswd file, than it is to secure + a database which might have more access interfaces.

+ diff --git a/docs/manual/mod/mod_authz_host.xml b/docs/manual/mod/mod_authz_host.xml index a4681b67f4..5319188f45 100644 --- a/docs/manual/mod/mod_authz_host.xml +++ b/docs/manual/mod/mod_authz_host.xml @@ -4,10 +4,8 @@ mod_authz_host - Group authorizations based on host (name or IP address) - Base mod_authz_host.c authz_host_module @@ -50,18 +48,15 @@ address) Allow - Controls which hosts can access an area of the server - Allow from - all|host|env=env-variable - [host|env=env-variable] ... + Allow from all|host|env=env-variable +[host|env=env-variable] ... directory.htaccess Limit -

The Allow directive affects which hosts can access an area of the server. Access can be controlled by hostname, IP Address, IP Address range, or by other @@ -81,39 +76,53 @@ server

A (partial) domain-name
-
Example: Allow from apache.org
- Hosts whose names match, or end in, this string are allowed +
+ Example: + Allow from apache.org + +

Hosts whose names match, or end in, this string are allowed access. Only complete components are matched, so the above example will match foo.apache.org but it will not match fooapache.org. This configuration will cause the server to perform a reverse DNS lookup on the client IP address, regardless of the setting of the HostnameLookups - directive.

+ directive.

A full IP address
-
Example: Allow from 10.1.2.3
- An IP address of a host allowed access
+
+ Example: + Allow from 10.1.2.3 + +

An IP address of a host allowed access

A partial IP address
-
Example: Allow from 10.1
- The first 1 to 3 bytes of an IP address, for subnet - restriction.
+
+ Example: + Allow from 10.1 + +

The first 1 to 3 bytes of an IP address, for subnet + restriction.

A network/netmask pair
-
Example: Allow from - 10.1.0.0/255.255.0.0
- A network a.b.c.d, and a netmask w.x.y.z. For more - fine-grained subnet restriction.
+
+ Example: + Allow from 10.1.0.0/255.255.0.0 + +

A network a.b.c.d, and a netmask w.x.y.z. For more + fine-grained subnet restriction.

A network/nnn CIDR specification
-
Example: Allow from 10.1.0.0/16
- Similar to the previous case, except the netmask consists of - nnn high-order 1 bits.
+
+ Example: + Allow from 10.1.0.0/16 + +

Similar to the previous case, except the netmask consists of + nnn high-order 1 bits.

Note that the last three examples above match exactly the @@ -131,43 +140,39 @@ server Allow directive allows access to the server to be controlled based on the existence of an environment variable. When Allow from - env=env-variable is specified, then the request is - allowed access if the environment variable env-variable + env=env-variable is specified, then the request is + allowed access if the environment variable env-variable exists. The server provides the ability to set environment variables in a flexible way based on characteristics of the client request using the directives provided by - mod_setenvif. Therefore, this directive can be + mod_setenvif. Therefore, this directive can be used to allow access based on such factors as the clients User-Agent (browser type), Referer, or other HTTP request header fields.

- -Example: -SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
-<Directory /docroot>
-   Order Deny,Allow
-   Deny from all
-   Allow from env=let_me_in
-</Directory> - + Example: + SetEnvIf User-Agent ^KnockKnock/2.0 let_me_in
+ <Directory /docroot>
+ + Order Deny,Allow
+ Deny from all
+ Allow from env=let_me_in
+ + </Directory> +

In this case, browsers with a user-agent string beginning with KnockKnock/2.0 will be allowed access, and all others will be denied.

 - - Deny - Controls which hosts are denied access to the server - - Deny from - all|host|env=env-variable - [host|env=env-variable] ... + Deny from all|host|env=env-variable +[host|env=env-variable] ... directory.htaccess Limit @@ -179,43 +184,38 @@ server identical to the arguments for the Allow directive.

- - Order - Controls the default access state and the order in which Allow and Deny are evaluated. - - Order ordering + Order ordering Order Deny,Allow directory.htaccess Limit -

The Order directive controls the default access state and the order in which Allow and Deny directives are evaluated. - Ordering is one of

+ Ordering is one of

-
Deny,Allow
+
Deny,Allow
The Deny directives are evaluated before the Allow directives. Access is - allowed by default. Any client which does not match a + allowed by default. Any client which does not match a Deny directive or does match an Allow directive will be allowed access to the server.
-
Allow,Deny
+
Allow,Deny
The Allow directives are evaluated before the Deny directive will be denied access to the server.
-
Mutual-failure
+
Mutual-failure
Only those hosts which appear on the Allow list and do not appear on @@ -235,7 +235,7 @@ evaluated. configuration.
-

Keywords may only be separated by a comma; no whitespace is +

Keywords may only be separated by a comma; no whitespace is allowed between them. Note that in all cases every Allow and Deny statement is evaluated.

@@ -243,11 +243,11 @@ evaluated.

In the following example, all hosts in the apache.org domain are allowed access; all other hosts are denied access.

- + Order Deny,Allow
Deny from all
- Allow from apache.org
- + Allow from apache.org +

In the next example, all hosts in the apache.org domain are allowed access, except for the hosts which are in the @@ -255,11 +255,11 @@ evaluated. in the apache.org domain are denied access because the default state is to deny access to the server.

- - Order Allow,Deny
- Allow from apache.org
- Deny from foo.apache.org
- + + Order Allow,Deny
+ Allow from apache.org
+ Deny from foo.apache.org +

On the other hand, if the Order in the last example is changed to Deny,Allow, all hosts will @@ -275,13 +275,15 @@ evaluated. access to a part of the server even in the absence of accompanying Allow and Deny directives because of its effect - on the default access state. For example,

+ on the default access state. For example,

- + <Directory /www>
-   Order Allow,Deny
+ + Order Allow,Deny
+ </Directory> - +

will deny all access to the /www directory because the default access state will be set to @@ -303,7 +305,6 @@ evaluated. href="../sections.html">How Directory, Location and Files sections work.

 - diff --git a/docs/manual/mod/mod_authz_user.xml b/docs/manual/mod/mod_authz_user.xml new file mode 100644 index 0000000000..0cbe770d6b --- /dev/null +++ b/docs/manual/mod/mod_authz_user.xml @@ -0,0 +1,48 @@ + + + + + +mod_authz_user +User Authorization +Base +mod_authz_user.c +authz_user_module +Available in Apache 2.1 and later + + +

This module provides authorization capabilities so that + authenticated users can be allowed or denied access to portions + of the web site. mod_authz_user grants + access if the authenticated user is listed in a Require user + directive. Alternatively require valid-user can be used to + grant access to all successfully authenticated users.

+ +Require +Satisfy + + +AuthzUserAuthoritative +Sets whether authorization will be passed on to lower level +modules +AuthzUserAuthoritative On|Off +AuthzUserAuthoritative On +directory.htaccess + +AuthConfig + + +

Setting the AuthzUserAuthoritative + directive explicitly to Off allows for + user authorization to be passed on to lower level modules (as defined + in the modules.c files) if there is no + user matching the supplied userID.

+ +

By default, control is not passed on and an unknown user + will result in an Authentication Required reply. Not + setting it to Off thus keeps the system secure and forces + an NCSA compliant behaviour.

+ + + + diff --git a/docs/manual/sitemap.xml b/docs/manual/sitemap.xml index 48762e01f1..67bb4d6302 100644 --- a/docs/manual/sitemap.xml +++ b/docs/manual/sitemap.xml @@ -135,9 +135,12 @@ Server on HPUX mod_authn_anon.xml mod_authn_dbm.xml mod_authn_file.xml + mod_authn_default.xml mod_authz_dbm.xml + mod_authz_default.xml mod_authz_groupfile.xml mod_authz_host.xml + mod_authz_user.xml mod_auth_ldap.xml mod_autoindex.xml mod_cache.xml