# HG changeset patch
# User paulb
# Date 1085940039 0
# Node ID b0518bb7d1c40ae03235b0f9adc5daf6325c9d4a
# Parent  bffcee91e1f4c622dc1003c741944f80ce9724be
[project @ 2004-05-30 18:00:39 by paulb]
Updated/improved the authentication/authorisation documentation.

diff -r bffcee91e1f4 -r b0518bb7d1c4 docs/AUTH.txt
--- a/docs/AUTH.txt	Sun May 30 17:44:59 2004 +0000
+++ b/docs/AUTH.txt	Sun May 30 18:00:39 2004 +0000
@@ -7,7 +7,8 @@
   * Use of authenticators, where the "remote user" is set in the
     server/framework environment and tested in the application.
 
-  * Use of the LoginRedirect and Login resources.
+  * Use of the WebStack.Resources.LoginRedirect and WebStack.Resources.Login
+    modules.
 
 Application-wide Authenticators
 -------------------------------
@@ -24,32 +25,57 @@
 In this mechanism, authenticators rely on authentication information from the
 server/framework and have a "global" effect on access to the application.
 
-LoginRedirect and Login Resources
----------------------------------
+LoginRedirect and Login Modules
+-------------------------------
 
-The LoginRedirect and Login resources provide a single sign-on environment for
-WebStack applications. Unlike the authenticator-only approach, each application
-or part of an application utilising this mechanism must be wrapped inside a
-LoginRedirect resource which determines whether a given transaction contains
-information identifying the application's user.
+The LoginRedirect and Login modules provide a single sign-on environment for
+WebStack applications. Unlike the authenticator-only approach, each
+application or part of an application utilising this mechanism must be wrapped
+inside a LoginRedirectResource object which determines whether a given
+transaction contains information identifying the application's user.
 
-Should sufficient information be present in the transaction, the user is allowed
-to access the application and is identified in the normal way (ie. the
-Transaction object's get_user method). Otherwise, a redirect occurs to the Login
-resource which then presents a login form to be completed by the user.
+Should sufficient information be present in the transaction, the user is
+allowed to access the application and is identified in the normal way (ie. the
+Transaction object's get_user method). Otherwise, a redirect occurs to a login
+screen provided by a LoginResource object which then presents a login form to
+be completed by the user.
 
-The Login resource verifies the identity of the user, testing the supplied
-credentials against the credentials database specified in the deployment of the
-resource. Upon successful authentication, the user is redirected back to the
-application, which should let the user gain access.
+The LoginResource object verifies the identity of the user, testing the
+supplied credentials against the credentials database specified in the
+deployment of the resource. Upon successful authentication, the user is
+redirected back to the application, which should let the user gain access.
 
 Some server/framework environments do not permit automatic redirection back to
 the application, notably Apache/mod_python. In such cases, a success screen is
 presented to the user with a link to the application they were attempting to
 access.
 
-In this mechanism, authenticators are employed, but only in the Login resource
-in order to verify the credentials of users. The LoginRedirector is the actual
-component that determines access to the application by testing whether the
-supplied authentication information is valid and redirecting them to the Login
-resource if this is not the case.
+In this mechanism, authenticators are employed, but only to verify the
+credentials of users when LoginResource or LoginRedirectResource objects are
+accessed.
+
+Anonymous Access
+----------------
+
+With application-wide authenticators, anonymous access to resources and
+applications can be difficult to permit alongside access by specific users,
+mostly because servers and frameworks which employ HTTP authentication schemes
+do so globally for a given application.
+
+With the LoginRedirect and Login modules, it is possible to declare a
+particular request parameter which must be present in the URL used to access a
+particular application for the client to be given anonymous access.
+Consequently, anonymous users are then identified specially with a special
+username that can also be configured.
+
+Logout Functions
+----------------
+
+With application-wide authenticators, a logout function may not be available
+if the server/framework has been configured to use HTTP authentication
+schemes, since no such function is defined for such schemes.
+
+With the LoginRedirect and Login modules, it is possible to declare a
+particular request parameter which must be present in the URL used to access a
+particular application for the client to be logged out. A special logout
+confirmation URL may also be configured.