[gatein-commits] gatein SVN: r8081 - portal/trunk/docs/reference-guide/en-US/modules/AuthenticationAndIdentity.
do-not-reply at jboss.org
do-not-reply at jboss.org
Wed Nov 16 10:15:20 EST 2011
Author: mposolda
Date: 2011-11-16 10:15:20 -0500 (Wed, 16 Nov 2011)
New Revision: 8081
Modified:
portal/trunk/docs/reference-guide/en-US/modules/AuthenticationAndIdentity/SSO.xml
Log:
GTNPORTAL-2277 SSO valve documentation upgrade.
Modified: portal/trunk/docs/reference-guide/en-US/modules/AuthenticationAndIdentity/SSO.xml
===================================================================
--- portal/trunk/docs/reference-guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-16 10:06:58 UTC (rev 8080)
+++ portal/trunk/docs/reference-guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-16 15:15:20 UTC (rev 8081)
@@ -43,15 +43,26 @@
Author [w/email]: Marek Posolda (mposolda at redhat.com)
-->
<para>
- The JBoss SSO valve is useful to authenticate a user on one JBoss Enterprise Portal Platform node in a cluster and have that authentication automatically carry across to other nodes in the cluster.
+ The JBoss SSO valve is useful to authenticate a user on one &PRODUCT; node in a cluster and have that authentication automatically carry across to other nodes in the cluster.
</para>
<para>
This authentication can also be used in any other web applications which may require authentication, <emphasis role="bold">provided that these applications use same roles as the main portal instance</emphasis>. Attempting to use an SSO authentication in an application that uses different roles may create authorization errors (<emphasis role="bold">403</emphasis> errors, for example).
</para>
+ <note>
+ <para>
+ This behaviour is coming from the fact that same JAAS principal is added by SSO valve to all HTTP requests, even to other web applications.
+ So the same roles are required because of it. There is alternative that you can configure SSO valve with parameter <emphasis role="bold">requireReauthentication=true</emphasis>
+ , which will force SSO valve to perform reauthentication with saved credentials in each HTTP request against security domain of particular web application where the request is coming.
+ This will enforce that new principal for that web application will be created with updated roles for that web application.
+ In other words, when requireReauthentication is <emphasis role="bold">false</emphasis> (default state), you need to have same roles among web applications.
+ When requireReauthentication is <emphasis role="bold">true</emphasis> you need to have same username and passwords.
+ </para>
+ </note>
+
<para>
- More info about the JBoss SSO valve can be found at <ulink type="http" url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform/5/html/Administration_And_Configuration_Guide/clustering-http-sso.html" />.
+ More info about the JBoss SSO valve can be found at <ulink type="http" url="http://community.jboss.org/wiki/JBossWebSingleSignOn" />.
</para>
<para>
@@ -87,182 +98,111 @@
<step>
<para>
- To integrate with the JBoss SSO valve, follow <emphasis role="bold">one</emphasis> of the procedures below to make the necessary configuration changes in the Java Authentication and Authorization Service (<emphasis role="bold">JAAS</emphasis>):
+ For integration of SSO valve among different nodes of cluster, you need to ensure that all these nodes share the same domain (for example <emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>).
+ This domain needs to be configured with parameter <emphasis role="bold">cookieDomain</emphasis> of SSO valve. Thing is that SSO valve is adding cookie <emphasis role="bold">JSESSIONIDSSO</emphasis>,
+ which is by default bound only to host where the request is coming. When used cookieDomain parameter, cookie is bound to domain (like <emphasis>yourdomain.com</emphasis>),
+ which will ensure that it is shared among both hosts <emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>. So in this case, valve configuration can look like this:
</para>
-
- <itemizedlist>
- <listitem>
- <procedure id="proc-Reference_Guide_eXo_JCR_1.14-SSO_Integration-Call_the_JAAS_authentication_directly">
- <title>Call the JAAS authentication directly</title>
-
- <step>
- <para>
- Open the <filename>/<replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> file.
- </para>
- </step>
-
- <step>
- <para>
- Change the line that reads:
- </para>
-<programlisting language="XML" role="XML"><form name="loginForm" action="<%= contextPath + "/login"%>" method="post" style="margin: 0px;">
+<programlisting language="XML" role="XML"><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" cookieDomain="yourdomain.com" />
</programlisting>
- <para>
- to read:
- </para>
-<programlisting language="XML" role="XML"><form name="loginForm" action="<%= contextPath + "/private/j_security_check"%>" method="post" style="margin: 0px;">
-</programlisting>
- </step>
+ </step>
- <step>
- <para>
- Change the line that reads:
- </para>
-<programlisting language="XML" role="XML"><td><input class="UserName" name="username" value="<%=username%>"/></td>
-</programlisting>
- <para>
- to read:
- </para>
-<programlisting language="XML" role="XML"><td><input class="UserName" name="j_username" value="<%=username%>"/></td>
-</programlisting>
- </step>
-
- <step>
- <para>
- Change the line that reads:
- </para>
-<programlisting language="XML" role="XML"><td><input class="Password" type="password" name="password" value=""/></td>
-</programlisting>
- <para>
- to read:
- </para>
-<programlisting language="XML" role="XML"><td><input class="Password" type="password" name="j_password" value=""/></td>
-</programlisting>
- </step>
- </procedure>
- </listitem>
-
- <listitem>
- <procedure id="proc-Reference_Guide_eXo_JCR_1.14-SSO_Integration-Switch_to_BASIC_authentication">
- <title>Switch to <emphasis role="bold">BASIC</emphasis> authentication</title>
-
- <step>
- <para>
- Change the <parameter>auth-method</parameter> element in <filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> from <parameter>FORM</parameter> to <parameter>BASIC</parameter>:
- </para>
-<programlisting language="XML" role="XML"><login-config>
-<auth-method>BASIC</auth-method>
-<realm-name>gatein-domain</realm-name>
-<form-login-config>
- <form-login-page>/initiatelogin</form-login-page>
- <form-error-page>/errorlogin</form-error-page>
-</form-login-config>
-</programlisting>
- </step>
- </procedure>
- </listitem>
- </itemizedlist>
+ <step>
+ <para>
+ Another important thing is that both cluster nodes needs to be on same cluster (using same parameter <emphasis role="bold">-g</emphasis> and same parameter <emphasis role="bold">-u</emphasis> and also using parameter <emphasis role="bold">-Dexo.profiles=cluster</emphasis>).
+ It's also needed for them to share the same NFS directory and same database and apply all the configuration needed for &PRODUCT; cluster.
+ </para>
</step>
</procedure>
- <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve">
- <title>Testing the SSO Valve</title>
+ <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_in_a_physical_cluster">
+ <title>Testing SSO in a physical cluster</title>
<para>
- Once the JBoss SSO Valve has been enabled, it can be tested with the following steps:
+ In this example, we will try to simulate testing on more physical machines by simply using virtual hosts on single machine.
</para>
</formalpara>
- <procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve">
- <title>Testing the SSO Valve</title>
-
+ <procedure>
<step>
<para>
- Copy the <replaceable><PROFILE></replaceable> you enabled the valve in (<literal>all</literal>, for example) into two new profiles called <literal>node1</literal> and <literal>node2</literal>.
- </para>
+ If you are on Linux, you can configure file <emphasis role="bold">/etc/hosts</emphasis> to contain these lines:
+ </para>
+<programlisting>
+127.0.1.1 machine1.yourdomain.com
+127.0.1.2 machine2.yourdomain.com
+</programlisting>
</step>
-
<step>
<para>
- Run an instance of JBoss Enterprise Portal Platform using the <literal>node1</literal> profile on a local machine:
+ Open the <filename><replaceable><JBOSS_HOME></replaceable>/server/all/deploy/jbossweb.sar/server.xml</filename> file.
</para>
-<programlisting>./run.sh -c node1 -Djboss.service.binding.set=ports-default -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &
-</programlisting>
</step>
<step>
<para>
- Start another instance using the <literal>node2</literal> profile:
+ Uncomment the line:
</para>
-<programlisting>./run.sh -c node2 -Djboss.service.binding.set=ports-01 -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &
+<programlisting language="XML" role="XML"><!--
+<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />
+-->
</programlisting>
</step>
<step>
<para>
- Navigate to <ulink type="http" url="http://localhost:8080/portal/private/classic" /> and authenticate with the pre-configured user account " <systemitem> root </systemitem> " (password " <systemitem> gtn </systemitem> ").
+ And edit it to match the following:
</para>
+<programlisting language="XML" role="XML"><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" cookieDomain="yourdomain.com" />
+</programlisting>
+ <para>
+ This will ensure the <literal>JSESSIONIDSSO</literal> cookie is used in the correct domain, allowing the SSO authentication to occur.
+ </para>
</step>
<step>
<para>
- Navigate to <ulink type="http" url="http://localhost:8180/portal/private/classic" /> . You should be automatically authenticated as user <systemitem> root </systemitem> on this node as well.
+ Copy server configuration <emphasis role="bold">all</emphasis> and create another two configurations <emphasis role="bold">node1</emphasis> and <emphasis role="bold">node2</emphasis> from it.
</para>
</step>
- </procedure>
- <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_in_a_physical_cluster">
- <title>Enabling SSO in a physical cluster</title>
-
- <para>
- If you require SSO to work across a physical cluster of separate machines you will need to use the <parameter>cookieDomain</parameter> attribute of the SSO valve.
- </para>
- </formalpara>
-
- <procedure>
<step>
<para>
- Open the <filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/jbossweb.sar/server.xml</filename> file.
+ Start both cluster nodes with commands:
</para>
+<programlisting>
+./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &
+./run.sh -c node2 -b machine2.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &
+</programlisting>
</step>
<step>
<para>
- Uncomment the line:
+ Let's go to <ulink type="http" url="http://machine1.yourdomain.com:8080/portal">http://machine1.yourdomain.com:8080/portal</ulink> and login as some user.
</para>
-<programlisting language="XML" role="XML"><!--
-<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" />
--->
-</programlisting>
</step>
<step>
<para>
- And edit it to match the following:
+ Access some private url on second host like <ulink type="http" url="http://machine2.yourdomain.com:8080/portal/dologin">http://machine2.yourdomain.com:8080/portal/dologin</ulink>.
+ Now you should be logged directly into machine2 thanks to SSO valve.
</para>
-<programlisting language="XML" role="XML"><Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" cookieDomain="yourdomain.com" />
-</programlisting>
- <para>
- (Where <literal>yourdomain.com</literal> is the domain used in your cluster. For example; <ulink type="http" url="http://machine1.yourdomain.com:8080/portal/private/classic" /> and <ulink type="http" url="http://machine2.yourdomain.com:8080/portal/private/classic" /> )
- </para>
</step>
<step>
<para>
- Repeat the process in the other nodes in the cluster.
+ Logout from SSO initiating machine1.yourdomain.com should also logged you out from other cluster nodes. So you should be logout directly from machine2 as well.
</para>
</step>
+
</procedure>
- <para>
- This will ensure the <literal>JSESSIONIDSSO</literal> cookie is used in the correct domain, allowing the SSO authentication to occur.
- </para>
-
<formalpara id="form-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_with_Other_Web_Applications">
<title>Enabling SSO with Other Web Applications</title>
<para>
- As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance.
+ As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance
+ (unless you have <emphasis>requireReauthentication=true</emphasis> as mentioned above).
</para>
</formalpara>
@@ -275,7 +215,7 @@
<step>
<para>
- Open the <filename><replaceable><JBOSS_HOME></replaceable>/server/<replaceable><PROFILE></replaceable>/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows:
+ Open the <filename><replaceable><JBOSS_HOME></replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows:
</para>
<substeps>
@@ -317,19 +257,19 @@
<para>
Start a portal instance on one node:
</para>
-<programlisting>./run.sh -c node1 -Djboss.service.binding.set=ports-default -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &
+<programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &
</programlisting>
</step>
<step>
<para>
- Navigate to <ulink type="http" url="http://localhost:8080/portal/private/classic" /> and authenticate with the pre-configured user account "<systemitem> root </systemitem>" (password "<systemitem> gtn </systemitem>").
+ Navigate to <ulink type="http" url="http://machine1.yourdomain.com:8080/portal/private/classic" /> and authenticate with the pre-configured user account "<systemitem> root </systemitem>" (password "<systemitem> gtn </systemitem>").
</para>
</step>
<step>
<para>
- Navigate to <ulink type="http" url="http://localhost:8080/jmx-console" />. You should be automatically authenticated into the JMX Console.
+ Navigate to <ulink type="http" url="http://machine1.yourdomain.com:8080/jmx-console" />. You should be automatically authenticated into the JMX Console.
</para>
</step>
</procedure>
@@ -338,16 +278,16 @@
<title>Using SSO to Authenticate From the Public Page</title>
<para>
- The previous configuration changes in this section are useful if a user is using a private URL ( <ulink type="http" url="http://localhost:8080/portal/private/classic" />, for example) to log in to the portal instance.
+ The previous configuration changes in this section are useful if a user is using a secured URL ( <ulink type="http" url="http://localhost:8080/portal/private/classic" />, for example) to log in to the portal instance.
</para>
</formalpara>
<para>
- Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal ( <ulink type="http" url="http://localhost:8080/portal/public/classic" /> ).
+ Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal ( <ulink type="http" url="http://localhost:8080/portal/classic" /> ).
</para>
<para>
- To enable this functionality, the <guilabel>Sign In</guilabel> link must redirect to the <filename>login.jsp</filename> file edited earlier to call the JAAS authentication directly.
+ To enable this functionality, the <guilabel>Sign In</guilabel> link must redirect to some secured URL, which will ensure that JAAS authentication will be enforced directly without showing login dialog.
</para>
<procedure id="proc-Reference_Guide_eXo_JCR_1.14-Enabling_SSO_using_JBoss_SSO_Valve-Redirect_to_Use_SSO_Valve_Authentication">
@@ -380,10 +320,6 @@
</step>
</procedure>
</section>
-
-
-
-
<section id="sect-Reference_Guide-Single_Sign_On-CAS_Central_Authentication_Service">
<title>Central Authentication Service (CAS)</title>
More information about the gatein-commits
mailing list