# HG changeset patch
# User paulb
# Date 1095789601 0
# Node ID 27d97f3262375f0a0b0533b2f48e4e02b5bb1b3d
# Parent  43e23cde36c2f609053af3ac3448d527f0a9e9c8
[project @ 2004-09-21 18:00:01 by paulb]
Added notes on authentication/authorisation with Apache Tomcat.

diff -r 43e23cde36c2 -r 27d97f326237 docs/JavaServlet/NOTES.txt
--- a/docs/JavaServlet/NOTES.txt	Tue Sep 21 17:59:03 2004 +0000
+++ b/docs/JavaServlet/NOTES.txt	Tue Sep 21 18:00:01 2004 +0000
@@ -5,11 +5,13 @@
 jython tools/JavaServlet/build.py examples/JavaServlet/SimpleApp.py \
     examples/Common/Simple/ \
     . \
+    web.xml \
     $CATALINA_HOME/common/lib/activation.jar \
     $CATALINA_HOME/common/lib/mail.jar
 
-This identifies the handler (SimpleApp.py), the application package (Simple)
-and the directory where the WebStack package is found; it also specifies
+This identifies the handler (SimpleApp.py), the application package (Simple),
+the directory where the WebStack package is found (.), and the name of the
+template for the deployment descriptor (web.xml); it also specifies the
 library files which must also be deployed with the application (activation.jar
 and mail.jar from the Tomcat libraries in this case); it produces a directory
 called SimpleApp in the current directory. To deploy the Web application into
@@ -22,3 +24,34 @@
 can be used to visit the application:
 
 http://localhost:8080/SimpleApp/
+
+--------
+
+Authentication/authorisation with Apache Tomcat:
+
+In Apache Tomcat, it is not typically possible to use an authenticator with a
+WebStack resource without additional configuration being performed first:
+
+  * The web.xml template should be replaced with the protected-web.xml
+    template in the build.py command. This alternative template produces a
+    special deployment descriptor which introduces role-based authentication for
+    the application. Consequently, upon seeing that the application requires a
+    user with a given role, Tomcat will prompt for the username/password details
+    of a user with that role, and once such a user has been authenticated, the
+    resulting user identity is then made available via the API to the
+    application.
+
+  * The server.xml configuration file in Tomcat should declare the protected
+    application as a privileged context; for example:
+
+    <Context path="/AuthApp" docBase="AuthApp" privileged="true"/>
+
+  * The tomcat-users.xml configuration file should define suitable users and
+    roles; for example:
+
+    <role rolename="webstack"/>
+    <user username="badger" password="abc" roles="webstack"/>
+
+    Note that it is still possible for an authenticator to reject access to
+    users even if they have the role stated in the special deployment
+    descriptor.