Return-Path: Delivered-To: apmail-jakarta-tomcat-dev-archive@www.apache.org Received: (qmail 73118 invoked from network); 6 Oct 2003 09:43:39 -0000 Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12) by minotaur-2.apache.org with SMTP; 6 Oct 2003 09:43:39 -0000 Received: (qmail 74159 invoked by uid 500); 6 Oct 2003 09:43:05 -0000 Delivered-To: apmail-jakarta-tomcat-dev-archive@jakarta.apache.org Received: (qmail 74117 invoked by uid 500); 6 Oct 2003 09:43:05 -0000 Mailing-List: contact tomcat-dev-help@jakarta.apache.org; run by ezmlm Precedence: bulk List-Unsubscribe: List-Subscribe: List-Help: List-Post: List-Id: "Tomcat Developers List" Reply-To: "Tomcat Developers List" Delivered-To: mailing list tomcat-dev@jakarta.apache.org Received: (qmail 74103 invoked by uid 500); 6 Oct 2003 09:43:05 -0000 Received: (qmail 74099 invoked from network); 6 Oct 2003 09:43:05 -0000 Received: from unknown (HELO minotaur.apache.org) (209.237.227.194) by daedalus.apache.org with SMTP; 6 Oct 2003 09:43:05 -0000 Received: (qmail 73065 invoked by uid 1135); 6 Oct 2003 09:43:30 -0000 Date: 6 Oct 2003 09:43:30 -0000 Message-ID: <20031006094330.73064.qmail@minotaur.apache.org> From: remm@apache.org To: jakarta-tomcat-catalina-cvs@apache.org Subject: cvs commit: jakarta-tomcat-catalina/webapps/docs realm-howto.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N remm 2003/10/06 02:43:30 Modified: webapps/docs realm-howto.xml Log: - Add JAAS realm documentation. - Submitted by Adam Hardy. Revision Changes Path 1.10 +146 -0 jakarta-tomcat-catalina/webapps/docs/realm-howto.xml Index: realm-howto.xml =================================================================== RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/realm-howto.xml,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- realm-howto.xml 20 Sep 2003 20:47:21 -0000 1.9 +++ realm-howto.xml 6 Oct 2003 09:43:30 -0000 1.10 @@ -29,6 +29,7 @@ DataSourceRealm
JNDIRealm
MemoryRealm
+JAASRealm
Common Features

@@ -1168,6 +1169,151 @@ log file in the $CATALINA_HOME/logs directory. + + + + + + +
Introduction
+ +
JAASRealm is an implementation of the Tomcat +4 Realm interface that authenticates users through the Java +Authentication & Authorization Service (JAAS) framework, a Java +package that is available as an optional package in Java 2 SDK 1.3 and +is fully integrated as of SDK 1.4 .
+
Using JAASRealm gives the developer the ability to combine +practically any conceivable security realm with Tomcat's CMA.
+
JAASRealm is prototype for Tomcat of the proposed JAAS-based +J2EE authentication framework for J2EE v1.4, based on the JCP Specification +Request 196 to enhance container-managed security and promote +'pluggable' authentication mechanisms whose implementations would be +container-independent. +
+
Based on the JAAS login module and principal (see javax.security.auth.spi.LoginModule +and javax.security.Principal), you can develop your own +security mechanism or wrap another third-party mechanism for +integration with the CMA as implemented by Tomcat. +
+ +
Quick Start
+
To set up Tomcat to use JAASRealm with your own JAAS login module, + you will need to follow these steps:
+
+
Write your own LoginModule, User and Role classes based +on JAAS (see +the +JAAS Authentication Tutorial and +the JAAS Login Module +Developer's Guide) to be managed by the JAAS Login +Context (javax.security.auth.login.LoginContext) +
+
Although not specified in JAAS, you should create +seperate classes to distinguish between users and roles, extending javax.security.Principal, +so that Tomcat can tell which Principals returned from your login +module are users and which are roles (see org.apache.catalina.realm.JAASRealm). +
+
Place the compiled classes on Tomcat's classpath +
+
Set up a login.config file for Java (see JAAS +LoginConfig file) and tell Tomcat where to find it by specifying +its location to the JVM, for instance by setting the environment +variable: JAVA_OPTS=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/conf/jaas.config
+
Configure your security-constraints in your web.xml for +the resources you want to protect
+
Configure the JAASRealm module in your server.xml
+
Restart Tomcat 4 if it is already running.
+
+
Realm Element Attributes
+
To configure JAASRealm as for step 6 above, you create +a <Realm> element and nest it in your +$CATALINA_HOME/conf/server.xml +file within your <Engine> node. The following attributes +are supported by this implementation:
+ + + + +
The fully qualified Java class name of this Realm implementation. + You MUST specify the value + "org.apache.catalina.realm.MemoryRealm" here.
+ + + +
The level of debugging detail logged by this Realm + to the associated Logger. Higher numbers + generate more detailed output. If not specified, the default + debugging detail level is zero (0).
+ + + +
The name of the realm as configured in your login configuration file + (JAAS LoginConfig).
+ + + +
A comma-seperated list of the names of the classes that you have made + for your user Principals.
+ + + +
A comma-seperated list of the names of the classes that you have made + for your role Principals.
+ + + + +
Example
+ +
Here is an example of how your server.xml snippet should look.
+ + +<Realm className="org.apache.catalina.realm.JAASRealm" + appName="MyFooRealm" + userClassNames="org.foobar.realm.FooUser" + roleClassNames="org.foobar.realm.FooRole" + debug="99"/> + + +
It is the responsibility of your login module to create and save User and +Role objects representing Principals for the user +(javax.security.auth.Subject). If your login module doesn't +create a user object but also doesn't throw a login exception, then the +Tomcat CMA will break and you will be left at the +http://localhost:8080/myapp/j_security_check URI or at some other +unspecified location.
+ +
The flexibility of the JAAS approach is two-fold:
+
+
you can carry out whatever processing you require behind +the scenes in your own login module.
+
you can plug in a completely different LoginModule by changing the configuration +and restarting the server, without any code changes to your application.
+
+ +
Additional Notes
+
+
+When a user attempts to access a protected resource for +the first time, Tomcat 4 will call the authenticate() +method of this Realm. Thus, any changes you have made in +the security mechanism directly (new users, changed passwords or +roles, etc.) will be immediately reflected.
+
Once a user has been authenticated, the user (and his or +her associated roles) are cached within Tomcat for the duration of +the user's login. (For FORM-based authentication, that means until +the session times out or is invalidated; for BASIC authentication, +that means until the user closes their browser). Any changes to the +security information for an already authenticated user will not +be reflected until the next time that user logs on again.
+
Debugging and exception messages logged by this Realm +will be recorded by the Logger that is associated with our +surrounding Context, Host, or Engine. +By default, the corresponding Logger will create a log file in the $CATALINA_HOME/logs +directory.
+
--------------------------------------------------------------------- To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org