Author: remy.maucherat(a)jboss.com Date: 2008-09-10 09:00:44 -0400 (Wed, 10 Sep 2008) New Revision: 773 Modified: trunk/webapps/docs/changelog.xml trunk/webapps/docs/config/realm.xml trunk/webapps/docs/realm-howto.xml Log: - Add combined realm doc. Modified: trunk/webapps/docs/changelog.xml =================================================================== --- trunk/webapps/docs/changelog.xml 2008-09-09 14:32:12 UTC (rev 772) +++ trunk/webapps/docs/changelog.xml 2008-09-10 13:00:44 UTC (rev 773) @@ -40,7 +40,7 @@ <subsection name="Coyote"> <changelog> <fix> - Fix a rare problem identifying AJP body packets that should be dropped. (remm) + Fix a rare problem identifying AJP body packets that should be dropped. (jfclere) </fix> </changelog> </subsection> Modified: trunk/webapps/docs/config/realm.xml =================================================================== --- trunk/webapps/docs/config/realm.xml 2008-09-09 14:32:12 UTC (rev 772) +++ trunk/webapps/docs/config/realm.xml 2008-09-10 13:00:44 UTC (rev 773) @@ -158,7 +158,30 @@ information on setting up container managed security using the JDBC Database Realm component.</p> + <h3>Combined Realm (org.apache.catalina.realm.CombinedRealm)</h3> + <p><strong>CombinedRealm</strong> is an implementation of the Tomcat 6 + <code>Realm</code> interface that authenticates users through one or more + sub-Realms.</p> + + <p>Using CombinedRealm gives the developer the ability to combine multiple + Realms of the same or different types. This can be used to authenticate + against different sources, provide fall back in case one Realm fails or for + any other purpose that requires multiple Realms.</p> + + <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the + <code>Realm</code> element that defines the CombinedRealm. Authentication + will be attempted against each <code>Realm</code> in the order they are + listed. Authentication against any Realm will be sufficient to authenticate + the user.</p> + + <p>The Combined Realm implementation does not support any additional + attributes.</p> + + <p>See the <a href="../realm-howto.html">Container-Managed Security + Guide</a> for more information on setting up container managed security + using the Combined Realm component.</p> + <h3> DataSource Database Realm (org.apache.catalina.realm.DataSourceRealm) </h3> @@ -478,8 +501,15 @@ <section name="Nested Components"> - <p>No components may be nested inside a <strong>Realm</strong> element.</p> + <h3>Combined Realm Implementation</h3> + <p>If you are using the <em>Combined Realm Implementation</em> + <strong>&lt;Realm&gt;</strong> elements may be nested inside it.</p> + + <h3>Other Realm Implementations</h3> + + <p>No other Realm implementation supports nested components.</p> + </section> Modified: trunk/webapps/docs/realm-howto.xml =================================================================== --- trunk/webapps/docs/realm-howto.xml 2008-09-09 14:32:12 UTC (rev 772) +++ trunk/webapps/docs/realm-howto.xml 2008-09-10 13:00:44 UTC (rev 773) @@ -1409,6 +1409,61 @@ </subsection> +<subsection name="CombinedRealm"> + + <h3>Introduction</h3> + + <p><strong>CombinedRealm</strong> is an implementation of the + <code>Realm</code> interface that authenticates users through one or more + sub-Realms.</p> + + <p>Using CombinedRealm gives the developer the ability to combine multiple + Realms of the same or different types. This can be used to authenticate + against different sources, provide fall back in case one Realm fails or for + any other purpose that requires multiple Realms.</p> + + <p>Sub-realms are defined by nesting <code>Realm</code> elements inside the + <code>Realm</code> element that defines the CombinedRealm. Authentication + will be attempted against each <code>Realm</code> in the order they are + listed. Authentication against any Realm will be sufficient to authenticate + the user.</p> + + <h3>Realm Element Attributes</h3> + <p>To configure CombinedRealm, you create a <code>&lt;Realm&gt;</code> + element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> + file within your <code>&lt;Engine&gt;</code> or <code>&lt;Host&gt;</code>. + You can also nest inside a <code>&lt;Context&gt;</code> node in a + <code>context.xml</code> file. The following attributes are supported by + this implementation:</p> + +<attributes> + + <attribute name="className" required="true"> + <p>The fully qualified Java class name of this Realm implementation. + You <strong>MUST</strong> specify the value + "<code>org.apache.catalina.realm.CombinedRealm</code>" here.</p> + </attribute> + +</attributes> + +<h3>Example</h3> + +<p>Here is an example of how your server.xml snippet should look to use a +UserDatabase Realm and a DataSource Realm.</p> + +<source> +&lt;Realm className="org.apache.catalina.realm.CombinedRealm" &gt; + &lt;Realm className="org.apache.catalina.realm.UserDatabaseRealm" + resourceName="UserDatabase"/&gt; + &lt;Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" + dataSourceName="jdbc/authority" + userTable="users" userNameCol="user_name" userCredCol="user_pass" + userRoleTable="user_roles" roleNameCol="role_name"/&gt; +&lt;Realm/&gt; +</source> + +</subsection> + </section> </body>