# HG changeset patch
# User paulb
# Date 1085874915 0
# Node ID d65d1e81f242129db252cc598d1e004071a86070
# Parent  70f2aa715a61152565909c82aa0c9132b14cbaf2
[project @ 2004-05-29 23:55:15 by paulb]
Added notes on authentication and access control.

diff -r 70f2aa715a61 -r d65d1e81f242 docs/AUTH.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/AUTH.txt	Sat May 29 23:55:15 2004 +0000
@@ -0,0 +1,55 @@
+Authentication in WebStack
+--------------------------
+
+There are two principal methods of introducing authentication and applying
+access control to WebStack applications:
+
+  * 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.
+
+Application-wide Authenticators
+-------------------------------
+
+First, set up the usage of such authentication mechanisms in the
+server/framework environment. For example, introduce Auth directives in your
+Apache configuration (see docs/ModPython/NOTES.txt).
+
+Then, define an authenticator when deploying your application; this
+authenticator will respond with a decision when prompted by the server or
+underlying framework, either allowing or denying access for the user whose
+identity has been presented to the server/framework.
+
+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
+---------------------------------
+
+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.
+
+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.
+
+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.
+
+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.