documentation suggestions relating to user authentication

[Tom Metro <tm...@vl.com>]

How about listing an address on http://dev.apache.org/mailing-lists for
documentation bugs/suggestions? (FYI, I'm not subscribed to this list.)

Where do I send suggestions for the FAQ?

I'd like to suggest the following documentation clarifications:

On these pages:
http://www.apache.org/docs/mod/mod_auth.html#authauthoritative
http://www.apache.org/docs/mod/mod_auth_db.html#authdbauthoritative
http://www.apache.org/docs/mod/mod_auth_dbm.html#authdbmauthoritative

There is a paragraph that reads:

 Setting the AuthAuthoritative 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 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.

I find that this raises more questions than it answers and doesn't get
across the essence of this directive. I find it is much clearer to
describe the inverse case (as is done in the mod_auth_anon
documentation):

"When the *Authoritative directive for a module is set to 'on', and that
module is used to authenticate a user, an authentication failure results
in an error message being returned and no other authentication scheme
will be tried. Setting *Authoritative to 'off' allows other schemes to
be tried in the event that the current scheme fails to authenticate the
user."

Or something along those lines. It probably needs to be modified to
include authorization, if that's part of the picture.


On page:
http://www.apache.org/docs/mod/core.html#require

It should be noted here that there is no corresponding directive or
parameter for the require directive that will cause it to be disabled
once it has been activated for a directory tree. I ran into this problem
when I tried disabling authentication for a subdirectory that had a
parent directory containing a require directive. I've seen this asked
about on Usenet several times. As far as I know there isn't a direct
solution (there are workarounds using "Satisfy any" or overriding with
directives in one of the *.conf files rather than in the .htaccess
file), and so it should be noted until/if the code changes.


There should be a document that consolidates all the fragments of
information that explains how .htaccess files are processed. One thing I
haven't seen pointed out is that a .htaccess file appears to be
equivalent to:

<Directory /current/directory>
# contents of .htaccess file
</Directory>

And likewise a document that fully explains the chain of events for
authorization and authentication. Currently this is partially documented
by the runtime directives documentation and partially by the Apache API
documentation, but neither offer a complete picture.

 -Tom

-- 
Tom Metro
Venture Logic                                     tmetro@vl.com
Newton, MA, USA