[jboss-cvs] JBossAS SVN: r82581 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Jan 1 15:45:49 EST 2009
Author: bstansberry at jboss.com
Date: 2009-01-01 15:45:49 -0500 (Thu, 01 Jan 2009)
New Revision: 82581
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml
Log:
[JBAS-4700] Update ClusteredSingleSignOn docs
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml 2009-01-01 01:48:15 UTC (rev 82580)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_HTTP.xml 2009-01-01 20:45:49 UTC (rev 82581)
@@ -542,19 +542,180 @@
</para>
</section>
-
-
+
<section id="clustering-http-sso">
<title>Using Clustered Single Sign On</title>
- <para>JBoss supports clustered single sign-on, allowing a user to authenticate to one web application on a JBoss server and to be recognized on all web applications, on that same machine or on another node in the cluster, that are deployed on the same virtual host. Authentication replication is handled by the same JBoss Cache Mbean that is used by the HTTP session replication service. Although session replication does not need to be explicitly enabled for the applications in question, the <literal>jboss-web-cluster.sar</literal> file needs to be deployed.
- </para>
+ <para>JBoss supports clustered single sign-on, allowing a user to authenticate
+ to one web application and to be recognized on all web
+ applications that are deployed on the same virtual host, whether or not they
+ are deployed on that same machine or on another node in the cluster.
+ Authentication replication is handled by JBoss Cache. Clustered single sign-on
+ support is a JBoss-specific extension of the non-clustered
+ <literal>org.apache.catalina.authenticator.SingleSignOn</literal>
+ valve that is a standard part of Tomcat and JBoss Web. Both the non-clustered
+ and clustered versions allow users to sign on to any one of the web apps
+ associated with a virtual host and have their identity recognized by all
+ other web apps on the same virtual host. The clustered version brings the
+ added benefits of enabling SSO failover and allowing a load balancer to direct
+ requests for different webapps to different servers, while maintaining the SSO.
+ </para>
+
+ <section id="clustering-sso-configuration">
+ <title>Configuration</title>
<para>
- To enable single sign-on, you must add the <literal>ClusteredSingleSignOn</literal> valve to the appropriate <literal>Host</literal> elements of the tomcat <literal>server.xml</literal> file. The valve configuration is shown here:
+ To enable clustered single sign-on, you must add the <literal>ClusteredSingleSignOn</literal>
+ valve to the appropriate <literal>Host</literal> elements of the
+ <literal>JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml</literal> file.
+ The valve element is already included in the standard file; you just need
+ to uncomment it. The valve configuration is shown here:
</para>
- <programlisting><Valve className="org.jboss.web.tomcat.tc5.sso.ClusteredSingleSignOn" /></programlisting>
+ <programlisting><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /></programlisting>
+
+ <para>The element supports the following attributes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">className</emphasis> is a required attribute
+ to set the Java class name of the valve implementation to use. This must
+ be set to <literal>org.jboss.web.tomcat.service.sso.ClusteredSingleSign</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">cacheConfig</emphasis> is the name of the
+ cache configuration (see <xref linkend="jbosscache-cachemanager"/>) to use
+ for the clustered SSO cache. Default is <literal>clustered-sso</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">treeCacheName</emphasis> is deprecated; use <literal>cacheConfig</literal>.
+ Specifies a JMX ObjectName of the JBoss Cache MBean to use
+ for the clustered SSO cache. If no cache can be located from the
+ CacheManager service using the value of <literal>cacheConfig</literal>
+ (see <xref linkend="jbosscache-cachemanager"/>),
+ an attempt to locate an mbean registered in JMX under this ObjectName
+ will be made. Default value is <literal>jboss.cache:service=TomcatClusteringCache</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">cookieDomain</emphasis> is used to set the host domain
+ to be used for sso cookies. See <xref linkend="clustering-sso-cookie-domain"/> for more.
+ Default is <literal>"/"</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">maxEmptyLife</emphasis> is the maximum number of seconds
+ an SSO with no active sessions will be usable by a request. The clustered
+ SSO valve tracks what cluster nodes are managing sessions related to an
+ SSO. A positive value for this attribute allows proper handling of
+ shutdown of a node that is the only one that had handled any of the sessions
+ associated with an SSO. The shutdown invalidates the local copy of the
+ sessions, eliminating all sessions from the SSO. If maxEmptyLife were
+ zero, the SSO would terminate along with the local session copies.
+ But, backup copies of the sessions (if they are from clustered
+ webapps) are available on other cluster nodes. Allowing the SSO to live
+ beyond the life of its managed sessions gives the user time to make
+ another request which can fail over to a different cluster node, where
+ it activates the the backup copy of the session. Default is
+ <literal>1800</literal>, i.e. 30 minutes.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">processExpiresInterval</emphasis> is the minimum number
+ of seconds between efforts by the valve to find and invalidate SSO's
+ that have exceeded their 'maxEmptyLife'. Does not imply effort will be
+ spent on such cleanup every 'processExpiresInterval', just that it
+ won't occur more frequently than that. Default is <literal>60</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">requireReauthentication</emphasis> is a flag to determine
+ whether each request needs to be reauthenticated to the security <emphasis>Realm</emphasis>.
+ If "true", this Valve uses cached security credentials (username and password)
+ to reauthenticate to the JBoss Web security <emphasis>Realm</emphasis>
+ each request associated with an SSO session. If <literal>false</literal>,
+ the valve can itself authenticate requests based on the presence of a
+ valid SSO cookie, without rechecking with the <emphasis>Realm</emphasis>.
+ Setting to <literal>true</literal> can allow web applications with
+ different <literal>security-domain</literal> configurations to share an
+ SSO. Default is <literal>false</literal>.</para>
+ </listitem>
+ </itemizedlist>
+
</section>
+ <section id="clustering-sso-behavior">
+ <title>SSO Behavior</title>
+ <para>The user will not be challenged as long as he accesses only
+ unprotected resources in any of the web applications on the virtual host.</para>
+
+ <para>Upon access to a protected resource in any web app, the user will
+ be challenged to authenticate, using the login method defined for the web app.</para>
+
+ <para>Once authenticated, the roles associated with this user will be
+ utilized for access control decisions across all of the associated web
+ applications, without challenging the user to authenticate themselves to
+ each application individually.</para>
+
+ <para>If the web application invalidates a session (by invoking the
+ <literal>javax.servlet.http.HttpSession.invalidate()</literal> method),
+ the user's sessions in all web applications will be invalidated.</para>
+
+ <para>A session timeout does not invalidate the SSO if other sessions
+ are still valid.</para>
+ </section>
+
+ <section id="clustering-sso-limitations">
+ <title>Limitations</title>
+ <para>There are a number of known limitations to this Tomcat valve-based
+ SSO implementation:
+
+ <itemizedlist>
+ <listitem><para>Only useful within a cluster of JBoss servers;
+ SSO does not propagate to other resources.</para></listitem>
+ <listitem><para>Requires use of container managed authentication
+ (via <literal><login-config></literal> element in <literal>web.xml</literal>)</para></listitem>
+ <listitem><para>Requires cookies. SSO is maintained via a cookie and URL rewriting is not supported.</para></listitem>
+ <listitem><para>Unless <literal>requireReauthentication</literal> is set
+ to <literal>true</literal>, all web applications configured for the same
+ SSO valve must share the same JBoss Web <literal>Realm</literal> and
+ JBoss Security <literal>security-domain</literal>. This means:
+ <itemizedlist>
+ <listitem><para>In <literal>server.xml</literal> you can nest the
+ <literal>Realm</literal> element inside the <literal>Host</literal>
+ element (or the surrounding <literal>Engine</literal> element), but not
+ inside a <literal>context.xml</literal> packaged with one of the involved web applications.</para></listitem>
+ <listitem><para>The <literal>security-domain</literal> configured in
+ <literal>jboss-web.xml</literal> or <literal>jboss-app.xml</literal>
+ must be consistent for all of the web applications.</para></listitem>
+ <listitem><para>Even if you set <literal>requireReauthentication</literal>
+ to <literal>true</literal> and use a different <literal>security-domain</literal>
+ (or, less likely, a different <literal>Realm</literal>) for different webapps,
+ the varying security integrations must all accept the same credentials
+ (e.g. username and password).</para></listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="clustering-sso-cookie-domain">
+ <title>Configuring the Cookie Domain</title>
+ <para>As noted above the SSO valve supports a <literal>cookieDomain</literal>
+ configuration attribute. This attribute allows configuration of the SSO cookie's domain
+ (i.e. the set of hosts to which the browser will present the cookie).
+ By default the domain is <literal>"/"</literal>, meaning the browser
+ will only present the cookie to the host that issued it. The
+ <literal>cookieDomain</literal> attribute allows the cookie to be
+ scoped to a wider domain.</para>
+
+ <para>For example, suppose we have a case where two apps, with URLs
+ <literal>http://app1.xyz.com</literal> and <literal>http://app2.xyz.com</literal>,
+ that wish to share an SSO context. These apps could be running on different
+ servers in a cluster or the virtual host with which they are associated
+ could have multiple aliases. This can be supported with the following configuration:
+
+ <programlisting><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn"
+ cookieDomain="xyz.com" /></programlisting>
+ </para>
+ </section>
+ </section>
+
</chapter>
More information about the jboss-cvs-commits
mailing list