Author: smumford Date: 2011-11-17 22:58:04 -0500 (Thu, 17 Nov 2011) New Revision: 8092 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml epp/docs/branches/5.2/Reference_Guide/publican.cfg Log: Port gtn r8080-8082, fix Global Portlet wrt theute feedback, increment Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2011-11-18 02:57:59 UTC (rev 8091) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2011-11-18 03:58:04 UTC (rev 8092) @@ -9,7 +9,7 @@ <productname>JBoss Enterprise Portal Platform</productname> <productnumber>5.2</productnumber> <edition>5.2.0</edition> - <pubsnumber>7</pubsnumber> + <pubsnumber>8</pubsnumber> <abstract> <para> This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2011-11-18 02:57:59 UTC (rev 8091) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2011-11-18 03:58:04 UTC (rev 8092) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>5.2.0-8</revnumber> + <date>Tue Nov 15 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email></email> + </author> + <revdescription> + <simplelist> + <member>Staged for Beta release.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>5.2.0-7</revnumber> <date>Wed Nov 9 2011</date> <author> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-18 02:57:59 UTC (rev 8091) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2011-11-18 03:58:04 UTC (rev 8092) @@ -4,7 +4,7 @@ %BOOK_ENTITIES; ]> <section id="sect-Reference_Guide-SSO_Single_Sign_On"> - <title><remark>SSO - Single Sign On</remark></title> + <title>SSO - Single Sign On</title> <section id="sect-Reference_Guide-SSO_Single_Sign_On-Overview"> <title>Overview</title> <para> @@ -83,7 +83,26 @@ 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> + <title>Reauthentication</title> + <para> + This behavior is coming from the fact that same JAAS principal is added by SSO valve to all HTTP requests, even to other web applications. + </para> + + <para> + So the same roles are required because of it. There is an alternative that allows you to configure the SSO valve with the <parameter>requireReauthentication=true</parameter> parameter, which will force the SSO valve to perform reauthentication with saved credentials in each HTTP request against security domain of particular web application where the request is coming. + </para> + + <para> + This will ensure that a new principal for that web application will be created with updated roles for that web application. + </para> + + <para> + In other words; when <parameter>requireReauthentication</parameter> is <emphasis role="bold">false</emphasis> (the default state), you need to have the same roles among web applications. When <parameter>requireReauthentication</parameter> 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...;. </para> <para> @@ -100,10 +119,10 @@ <para> For a <emphasis>non-clustered</emphasis> implementation, uncomment: </para> +<programlisting language="XML" role="XML">&lt;Valve className="org.apache.catalina.authenticator.SingleSignOn" /&gt; + </programlisting> + </listitem> -<programlisting language="XML" role="XML"><![CDATA[<Valve className="org.apache.catalina.authenticator.SingleSignOn" /> -]]></programlisting> - </listitem> <listitem> <para> For a <emphasis>clustered</emphasis> implementation, uncomment: @@ -116,160 +135,115 @@ </step> <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 implementation of the SSO valve among the different nodes of cluster, all the nodes must share the same domain (<emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>, for example). </para> - <itemizedlist> - <listitem> - <procedure> - <title>Call the JAAS authentication directly</title> - <step> <para> - Open the <filename>/<replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> file. + This domain needs to be configured in the SSO valve parameter <parameter>cookieDomain</parameter>. This is required because the SSO valve adds the cookie <emphasis role="bold">JSESSIONIDSSO</emphasis>, which is, by default bound only to the host where the request is originating. </para> - </step> - <step> + <para> - Change the line that reads: + When the <parameter>cookieDomain</parameter> parameter is used, the cookie is bound to the 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>. </para> -<programlisting language="XML" role="XML"><![CDATA[<form name="loginForm" action="<%= contextPath + "/login"%>" method="post" style="margin: 0px;"> -]]></programlisting> <para> - to read: + So in this case, the valve configuration would be: </para> -<programlisting language="XML" role="XML"><![CDATA[<form name="loginForm" action="<%= contextPath + "/private/j_security_check"%>" method="post" style="margin: 0px;"> -]]></programlisting> +<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" +cookieDomain="yourdomain.com" /&gt; +</programlisting> </step> <step> <para> - Change the line that reads: + 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>). </para> -<programlisting language="XML" role="XML"><![CDATA[<td><input class="UserName" name="username" value="<%=username%>"/></td> -]]></programlisting> - <para> - to read: - </para> -<programlisting language="XML" role="XML"><![CDATA[<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"><![CDATA[<td><input class="Password" type="password" name="password" value=""/></td> -]]></programlisting> + <para> - to read: + They must also share the same NFS directory and the same database and apply all the configuration needed for JBoss Enterprise Portal Platform cluster. </para> -<programlisting language="XML" role="XML"><![CDATA[<td><input class="Password" type="password" name="j_password" value=""/></td> -]]></programlisting> </step> </procedure> - </listitem> - <listitem> - <procedure id="proc-Reference_Guide-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>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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"><![CDATA[<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> - </procedure> - <formalpara> - <title>Testing the SSO Valve</title> - <para> - Once the JBoss SSO Valve has been enabled, it can be tested with the following steps: + <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> + 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-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> <title>Testing the SSO Valve</title> <step> <para> - Copy the <replaceable>&lt;PROFILE&gt;</replaceable> you enabled the valve in (<literal>all</literal>, for example) into two new profiles called <literal>node1</literal> and <literal>node2</literal>. + If you are using a Linux system, 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>&lt;JBOSS_HOME&gt;</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 &amp; -</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 &amp; +<programlisting language="XML" role="XML">&lt;!-- +&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt; +--&gt; </programlisting> </step> <step> <para> - Navigate to <ulink type="http" url="http://localhost:8080/portal/private/classic"></ulink> 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">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" +cookieDomain="yourdomain.com" /&gt; +</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"></ulink>. 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-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>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</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 &amp; +./run.sh -c node2 -b machine2.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &amp; +</programlisting> </step> <step> <para> - Uncomment the line: + Go to <ulink type="http" url="http://machine1.yourdomain.com:8080/portal">http://machine1.yourdomain.com:8080/portal</ulink> and login as a user. </para> -<programlisting language="XML" role="XML"><![CDATA[<!-- -<Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /> ---> -]]></programlisting> + </step> <step> <para> - And edit it to match the following: + Access a private URL on the second host, such as <ulink type="http" url="http://machine2.yourdomain.com:8080/portal/dologin">http://machine2.yourdomain.com:8080/portal/dologin</ulink>, for example. </para> -<programlisting language="XML" role="XML"><![CDATA[<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"></ulink> and <ulink type="http" url="http://machine2.yourdomain.com:8080/portal/private/classic"></ulink>) + Now you should be logged directly into <literal>machine2</literal> thanks to SSO valve. </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-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. + <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 (unless you have the <parameter>requireReauthentication</parameter> parameter set to <literal>true</literal>). </para> </formalpara> <para> @@ -279,7 +253,7 @@ <title></title> <step> <para> - Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: + Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: </para> <substeps> <step> @@ -315,7 +289,7 @@ <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 &amp; +<programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; </programlisting> </step> <step> @@ -332,14 +306,14 @@ <formalpara> <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"></ulink>, 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"></ulink>, 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"></ulink>). </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> <title>Redirect to Use SSO Valve Authentication</title> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2011-11-18 02:57:59 UTC (rev 8091) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2011-11-18 03:58:04 UTC (rev 8092) @@ -3,8 +3,8 @@ <!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent"> %BOOK_ENTITIES; ]> -<chapter id="chap-Reference_Guide_eXo_JCR_1.14-Shared_portlet.xml"> - <title><remark>Shared <filename>portlet.xml</filename></remark></title> +<chapter id="chap-Reference_Guide_eXo_JCR_1.14-Shared_portlet.xml"> + <title>Shared <filename>portlet.xml</filename></title> <para> The Java Portlet Specification introduces <literal>PortletFilter</literal> as a standard approach to extend the behaviors of portlet objects. For example, a filter can transform the content of portlet requests and portlet responses. </para> @@ -13,19 +13,19 @@ </para> <procedure> <step> - <para> - Implement a <literal>PortletFilter</literal> object. - </para> + <para> + Implement a <literal>PortletFilter</literal> object. + </para> </step> <step> - <para> - Define the filter in portlet application deployment descriptor. - </para> + <para> + Define the filter in portlet application deployment descriptor. + </para> </step> <step> - <para> - Define the filter mapping in portlet definitions. - </para> + <para> + Define the filter mapping in portlet definitions. + </para> </step> </procedure> <para> @@ -35,48 +35,48 @@ <para> Global portlet metadata is declared in the <filename>portlet.xml</filename> file and conforms with the Portlet 2.0 XSD. </para> -<programlisting language="XML" role="XML">&lt;portlet-app version="1.0" xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"&gt; -&lt;/portlet-app&gt; +<programlisting language="XML" role="XML">&lt;portlet-app version="1.0" xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2... http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"&gt; +&lt;/portlet-app&gt; </programlisting> <para> - The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default The file path is <filename>/<replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/portlet.xml</filename> + The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default The file path is <filename>/<replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/portlet.xml</filename> </para> <para> <emphasis role="bold">For JBoss</emphasis>: The file path is <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/default/conf/gatein/portlet.xml</filename>. </para> - <section id="sect-Reference_Guide-Global_Metadata-Global_Metadata_Elements"> + <section id="sect-Reference_Guide-Global_Metadata-Global_Metadata_Elements"> <title>Global Metadata Elements</title> <para> The global <filename>portlet.xml</filename> file conforms, with some restrictions, to the portlet deployment descriptor schema defined in the Portlet Specification. In this file, the following elements are supported: </para> <orderedlist> <listitem> - <para> - <xref linkend="form-Reference_Guide_eXo_JCR_1.14-Global_Metadata_Elements-Portlet_Filter"/> - </para> + <para> + <xref linkend="form-Reference_Guide_eXo_JCR_1.14-Global_Metadata_Elements-Portlet_Filter"/> + </para> </listitem> <listitem> - <para> - Portlet Mode - </para> + <para> + Portlet Mode + </para> </listitem> <listitem> - <para> - Window State - </para> + <para> + Window State + </para> </listitem> </orderedlist> - <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Global_Metadata_Elements-Portlet_Filter"> + <formalpara id="form-Reference_Guide_eXo_JCR_1.14-Global_Metadata_Elements-Portlet_Filter"> <title>Portlet Filter</title> <para> Portlet filter mappings declared in the global <filename>portlet.xml</filename> file are applied across portlet applications. </para> - </formalpara> + </formalpara> <para> With the XML configuration below, the filter <literal>ApplicationMonitoringFilter</literal> involves in request handling on any deployed portlet. </para> @@ -115,7 +115,7 @@ </listitem> </orderedlist> <para> - The Application Monitoring Filter records statistic information about deployed portlets. The filter alternates the actual monitoring mechanism in WebUI Framework. + The Application Monitoring Filter records statistic information about deployed portlets. The filter alternates the actual monitoring mechanism in WebUI Framework. </para> </section> </chapter> Modified: epp/docs/branches/5.2/Reference_Guide/publican.cfg =================================================================== --- epp/docs/branches/5.2/Reference_Guide/publican.cfg 2011-11-18 02:57:59 UTC (rev 8091) +++ epp/docs/branches/5.2/Reference_Guide/publican.cfg 2011-11-18 03:58:04 UTC (rev 8092) @@ -5,7 +5,7 @@ type: Book brand: JBoss debug:1 -show_remarks: 1 +#show_remarks: 1 cvs_branch: DOCS-RHEL-6 cvs_root: :ext:cvs.devel.redhat.com:/cvs/dist cvs_pkg: JBoss_Enterprise_Portal_Platform-Reference_Guide-5.2-web-__LANG__ \ No newline at end of file