[gatein-commits] gatein SVN: r8977 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules/AuthenticationAndIdentity and 1 other directories.

Author: jaredmorgs Date: 2012-12-04 02:06:38 -0500 (Tue, 04 Dec 2012) New Revision: 8977 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml Log: BZ#856430 - Final incorporations for CAS work now committed, and staged Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-11-30 04:15:42 UTC (rev 8976) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-12-04 07:06:38 UTC (rev 8977) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.0.0-23</revnumber> + <date>Tue Dec 04 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#856430 - Incorporated final changes by Marek for CAS. These changes are considered final, and ready for release.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-22</revnumber> <date>Fri Nov 30 2012</date> <author> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-11-30 04:15:42 UTC (rev 8976) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-12-04 07:06:38 UTC (rev 8977) @@ -122,7 +122,7 @@ </para> </formalpara> </section> - <section id="sect-Reference_Guide-Authentication_Authorization_Intro-LoginModules"> + <section id="sect-Authentication_Authorization_Intro-Login_Modules"> <title>Login modules</title> <para> JBoss Portal Platform uses its own security domain (<emphasis role="bold">gatein-domain</emphasis>) with a set of predefined login modules. Login module configuration for <emphasis>gatein-domain</emphasis> is contained in the <filename>deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-11-30 04:15:42 UTC (rev 8976) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-04 07:06:38 UTC (rev 8977) @@ -334,23 +334,13 @@ </section> <section id="sect-SSO_Single_Sign_On_-Central_Authentication_Service"> <title><remark>BZ#856430</remark>Central Authentication Service (CAS)</title> - <para>The CAS Single Sign On (SSO) plug-in enables seamless integration between the platform and the CAS SSO framework. Further information about CAS can be found on the + <para>The CAS Single Sign On (SSO) plug-in enables seamless integration between the platform and the CAS SSO framework. General information about CAS can be found on the <ulink url="http://www.jasig.org/cas">Jasig website</ulink> . </para> - <para>The integration consists of two parts:</para> - <itemizedlist> - <listitem> - <para>Installing and configuring a CAS server.</para> - </listitem> - <listitem> - <para>Setting up the portal to use the CAS server.</para> - </listitem> - </itemizedlist> <section id="sect-CAS-Authentication_Process"> <title>Authentication Process</title> <para>The authentication process with CAS integration occurs in the following order:</para> - <remark>Docs Note - jmorgan - have taken the original process in https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... and have tried to break up some of the steps for clarity. If you could please verify these changes are accurate, that would be awesome, Marek.</remark> <orderedlist> <listitem> <para>A user visits the main portal page, and wishes to authenticate. The user clicks @@ -412,10 +402,7 @@ and saves the <emphasis role="italics">Identity</emphasis> object to the - <emphasis role="italics">IdentityRegistry</emphasis> - (See - <ulink url="https://docs.jboss.org/author/pages/viewpage.action?pageId=5426... and Authorization intro#Login modules</ulink> - for more details). + <emphasis role="italics">IdentityRegistry</emphasis>. For more information about login modules, refer to <xref linkend="sect-Authentication_Authorization_Intro-Login_Modules"/>. </para> </listitem> <listitem> @@ -427,7 +414,6 @@ <section id="sect-CAS-Logout_Workflow"> <title>Logout Process</title> <para>The logout process with CAS integration occurs in the following order:</para> - <remark>Docs Note - jmorgan - The same with this one Marek. Taken from the confluence page and reworked to introduce some separation into the steps. Just check my wording of each step to ensure I haven&apos;t changed the overall technical meaning with my changes. Cheers, Marek!</remark> <orderedlist> <listitem> <para>The authenticated user clicks the @@ -465,39 +451,24 @@ <para>For scope purposes, the setup instructions assume the following configuration outcomes: </para> <itemizedlist> <listitem> - <para>CAS 3.5 will be deployed on Tomcat 7 server, which will listen on - <emphasis role="italics">localhost:8888</emphasis></para> + <para>The CAS 3.5 is downloaded, and required changes are made to authentication plug-in, logout redirection, and CASTGC cookie configuration. </para> </listitem> <listitem> - <para>The portal will listen on - <emphasis role="italics">localhost:8080</emphasis></para> + <para>Once configured, Apache Maven is used to create the custom CAS web archive, suitable for deployment.</para> </listitem> + <listitem> + <para>The WAR is deployed to the Apache Tomcat server, which acts as the host for the CAS.</para> + </listitem> + <listitem> + <para>Apache Tomcat is configured to listen on <emphasis role="italics">localhost:8888</emphasis>.</para> + </listitem> + <listitem> + <para>JBoss Portal Platform is configured to listen on + <emphasis role="italics">localhost:8080</emphasis>.</para> + </listitem> </itemizedlist> - <section id="sect-CAS-Install_Tomcat_Server"> - <title>Install Apache Tomcat Server</title> - <para>Install and configure Apache Tomcat 7 before proceeding with other configuration relating to CAS. -</para> - <para>File name abbreviations in this section are described in <xref linkend="sect-File_Name_Conventions"/></para> - <procedure> - <title>Configuring Apache Tomcat for CAS</title> - <remark>Docs Note - redid the procedure with a view to Apache Tomcat, not Apache httpd. If installed from the Zip binary, does Apache Tomcat start a service like httpd (Step 4)?</remark> - <step> - <para>Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution.</para> - </step> - <step> - <para>Extract and install the binary on the server that is required to host CAS. This directory is now referred to as <replaceable>TOMCAT_DIST</replaceable>.</para> - </step> - <step> - <para>Edit <filename>TOMCAT_DIST/conf/server.xml</filename> and change port 8080 to 8888 to avoid a conflict with the default JBoss Portal Platform listen port.</para> - </step> - <step> - <para>Ensure port 8888 is open in the server firewall, and the service is enabled and running so the platform can communicate with Apache Tomcat on the same server. -</para> - </step> - </procedure> - </section> <section id="sect-CAS-Download_CAS"> - <title>Download CAS</title> + <title><remark>BZ#856430 </remark>Download CAS</title> <para> CAS can be downloaded from <ulink url="http://www.jasig.org/cas/download"/> @@ -505,16 +476,17 @@ <emphasis role="italics">CAS 3.5</emphasis> . More recent CAS versions may also work, however have not been officially tested as part of this specific configuration exercise. </para> + <remark>Docs Note - jmorgan - Marek, I originally incorrectly specified that an admin should extract the CAS source binary into the Tomcat server. It&apos;s my fault, because I didn&apos;t realise that you need to configure CAS first, *then* build the WAR, and finally deploy to Tomcat. The following sentence makes this much clearer now.</remark> <para> - Extract the downloaded file into a suitable location on the Tomcat server. This location will be referred to as + Extract the downloaded file into a suitable working directory. This location will be referred to as <code>CAS_DIR</code> - in subsequent instructions. + in subsequent configuration instructions. </para> </section> </section> <section id="sect-CAS-Modifying_CAS_Server"> <title>Modifying the CAS server</title> - <para>To configure the web archive as desired, the most effective way is to make the necessary changes directly in the CAS code base.</para> + <para>To configure the CAS server correctly, the most effective way is to make the necessary changes directly in the CAS code base. Follow the instructions in the sections below to make the required changes to the CAS code base, before using Maven to build the CAS web archive.</para> <section id="sect-CAS_Authentication_Plug-in"> <title>Authentication Plug-in </title> <para>While it is possible (and perfectly acceptable) for an administrator to configure CAS to retrieve user credentials from an external database, or from a LDAP server, it is also possible to use JBoss technology. </para> @@ -617,8 +589,34 @@ </variablelist> </section> </section> + <section id="sect-CAS-Install_Tomcat_Server"> + <title>Install Apache Tomcat Server</title> + <para>Install and configure Apache Tomcat 7, which provides the host server for the CAS server. </para> + <para>File name abbreviations in this section are described in <xref linkend="sect-File_Name_Conventions"/></para> + <procedure> + <title>Configuring Apache Tomcat for CAS</title> + <step> + <para>Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution.</para> + </step> + <step> + <para>Extract and install the binary on the server that is required to host CAS. This directory is now referred to as <replaceable>TOMCAT_DIST</replaceable>.</para> + </step> + <step> + <para>Edit <filename>TOMCAT_DIST/conf/server.xml</filename> and change port 8080 to 8888 to avoid a conflict with the default JBoss Portal Platform listen port.</para> + <remark>BZ#856430 - jmorgan - Added the new ports from the Confluence SSO Server Setup section</remark> + <important> + <para>If the Apache Tomcat server is installed on the same machine as JBoss Portal Platform, ensure other listen ports common to both servers are changed to prevent configuration issues. For example, change the Tomcat admin port from 8005 to 8805, and the Tomcat AJP port from 8009 to 8809.</para> + </important> + </step> + <step> + <para>Ensure all Apache Tomcat ports are open in the server firewall, and the service is enabled and running so the platform can communicate with Apache Tomcat on the same server. +</para> + </step> + </procedure> + </section> <section id="sect-CAS-Modifying_the_Portal"> <title>Modifying the Portal</title> + <para>Before building and deploying the Jasig CAS sever, configuration needs to be implemented on the JBoss Portal Platform server to prepare the portal for CAS integration.</para> <section id="sect-CAS_Portal_SSO_Primary_Configuration_File"> <title>Portal SSO Primary Configuration File</title> <para> @@ -748,6 +746,31 @@ </variablelist> </section> </section> + <section> + <title><remark>BZ#856430 </remark>Build and Deploy the CAS </title> + <remark>BZ#856430 - jmorgan - This is a new sections which captures the final step an admin needs to do to bring all the cofiguration together.</remark> + <para>Jasig CAS uses Apache Maven to build the <filename>cas.war</filename> file. Follow the instructions to produce this file, and deploy it to the Apache Tomcat server.</para> + <procedure> + <title>Building CAS, and Deploying to Tomcat</title> + <step> + <para>Install Maven by following the recommendations and links in the <ulink url="https://wiki.jasig.org/display/CASUM/Building+and+Deploying&quo... and Deploying section</ulink> of the Jasig CAS user documentation.</para> + </step> + <step> + <para>In a terminal, navigate to <filename>CAS_DIR/cas-server-webapp/</filename>, and run <command>mvn install</command>.</para> + </step> + <step> + <para>Copy <filename>CAS_DIR/cas-server-webapp/target/cas.war</filename> to <filename>TOMCAT_DIST/webapps</filename>.</para> + </step> + <step> + <para>Tomcat should be running by default, if the process has been followed up to this step. Start JBoss Portal Platform, and verify the server is running by opening <ulink url="http://localhost:8080/"/>.</para> + </step> + <step> + <para>Open <ulink url="http://localhost:8888/cas"/> to verify the CAS server has correctly deployed to Tomcat. If the link does not open the CAS login page, restart Apache Tomcat and try again.</para> + </step> + </procedure> + <remark>BZ#856430 - jmorgan - Added this &quot;wrap up&quot; statement that should describe what customers are able to do after following the procedure.</remark> + <para>The CAS server is now deployed to Tomcat, and the portal will now redirect users to the CAS login page when they click on the Sign In link.</para> + </section> </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> <title>Java Open Single Sign-On Project</title> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2012-11-30 04:15:42 UTC (rev 8976) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/PortalLifecycle.xml 2012-12-04 07:06:38 UTC (rev 8977) @@ -22,142 +22,77 @@ <para> During deployment, JBoss Portal Platform will automatically and transparently inject a servlet into the portlet application to be able to interact with it. This feature is dependent on the underlying servlet container but will work out of the box on the proposed bundles. </para> - <section> - <title>Advanced WCI Registration</title> - - <para> + <section> + <title>Advanced WCI Registration</title> + <para> JBoss Portal Platform integrates with the web container to perform tasks such as automatic detection and registration of web applications. This is used by the portal container to detect when portlets are deployed and is accomplished through the WCI (Web Container Integration) component. </para> - - <para> + <para> Some applications, especially Spring based portlets, may have requirements that specific servlets be started before any portlets are initialized. Although portlets and servlet initialization order are meant to be independent of each other, JBoss Portal Platform does have a way to get around these limitations imposed by these specific third party applications. </para> - - <para> + <para> As a workaround to this issue, two new, advanced features have been integrated into the WCI component; </para> - - <variablelist> - <title></title> - - <varlistentry> - <term>Disabling Automatic registration</term> - - <listitem> - <para> + <variablelist> + <title>Advanced Features</title> + <varlistentry> + <term>Disabling Automatic registration</term> + <listitem> + <para> By default WCI will register all web applications and the portlet container will then analyse the registered applications and initialize any portlets contained. If you do not wish for your web application to be automatically registered by the WCI component you can disable this feature. By disabling this feature you can prevent the automatic initialization of the portlet and specify later when you want it to be initialized. </para> - - <para> + <para> This is done by setting the <parameter>gatein.wci.native.DisableRegistration</parameter> context-param to <literal>true</literal> in the <filename>web.xml</filename> file of the application, as shown below: </para> -<programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration --> <context-param> <param-name>gatein.wci.native.DisableRegistration</param-name> <param-value>true</param-value> </context-param> ]]></programlisting> - </listitem> - </varlistentry> - - <varlistentry> - <term>Manual application deployment.</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Manual application deployment.</term> + <listitem> + <para> If you have disabled the automatic registration of your application in the first step, the portal container will not know about any of the portlets contained and will not be able to initialize them. WCI does have a servlet which can be used to manually register the web application. Since servlets can specify when they are deployed with regards to other servlets, we can use this to specify that the web application gets registered by WCI after another servlet has already been started. This means that the a servlet, for example the Spring servlet, can be initialized before any of the portlets. </para> - - <para> + <para> Below is an example <filename>web.xml</filename> file configured to ensure the <systemitem>MyCustomServlet</systemitem> will be initialized before the webapp is registered by WCI: </para> -<programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Disable the Native Application Registration --> <context-param> <param-name>gatein.wci.native.DisableRegistration</param-name> <param-value>true</param-value> </context-param> ]]></programlisting> -<programlisting language="XML" role="XML"><![CDATA[<!-- Register the Web Application Manually --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Register the Web Application Manually --> <servlet> <servlet-name>GateInServlet</servlet-name> <servlet-class>org.gatein.wci.api.GateInServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> ]]></programlisting> -<programlisting language="XML" role="XML"><![CDATA[<!-- Custom Servlet which will be initalised before the webapp is registered in WCI --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Custom Servlet which will be initalised before the webapp is registered in WCI --> <servlet> <servlet-name>MyCustomServlet</servlet-name> <servlet-class>my.custom.Servlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> ]]></programlisting> -<programlisting language="XML" role="XML"><![CDATA[<!-- Servlet Mapping for the Manual Registration --> + <programlisting language="XML" role="XML"><![CDATA[<!-- Servlet Mapping for the Manual Registration --> <servlet-mapping> <servlet-name>GateInServlet</servlet-name> <url-pattern>/gateinservlet</url-pattern> </servlet-mapping> ]]></programlisting> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> + </listitem> + </varlistentry> + </variablelist> + </section> </section> -<!-- -TODO: Define the added listener - --><!-- -<section id="sect-Reference_Guide-Portal_Lifecycle-The_Listener"> -<title>The Listener</title> -<para> -In the web.xml we can find servlet listener: -</para> --><!-- <programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/PortalDevelopment_PortalLifecycle/default158.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --><!-- <programlisting> &lt;!- ================================================================== -&gt; -&lt;!- LISTENER -&gt; -&lt;!- ================================================================== -&gt; -&lt;listener&gt; -&lt;listener-class&gt;org.exoplatform.portal.application.PortalSessionListener&lt;/listener-class&gt; -&lt;/listener&gt; -</programlisting> --><!-- <para> -That listener implements the HttpSessionListener which means it is called each time a session is created or destroyed; in other words, a session is created each time a user send a first request to the portal. That session is destroyed when he has not sent request to the portal for a long time or when he closes his browser. -</para> -<programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/PortalDevelopment_PortalLifecycle/PortalSessionListener.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --><!-- <programlisting>public class PortalSessionListener implements HttpSessionListener -</programlisting> --><!-- <para> -Only the destroy method of the Listener object is implemented and it is used to flush resources when a user portal session expires. Here is the code: -</para> --><!-- <programlisting language="Java" role="Java"><xi:include parse="text" href="../../extras/PortalDevelopment_PortalLifecycle/default159.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> --><!-- <programlisting> /** -* This method is called when a HTTP session of a Portal instance is destroyed. -* By default the session time is 30 minutes. -* -* In this method, we: -* 1) first get the portal instance name from where the session is removed. -* 2) Get the correct instance object from the Root container -* 3) Put the portal instance in the Portal ThreadLocal -* 4) Get the main entry point (WebAppController) from the current portal container -* 5) Extract from the WebAppController the PortalApplication object which is the entry point to -* the StateManager object -* 6) Expire the portal session stored in the StateManager -* 7) Finally, removes the WindowInfos object from the WindowInfosContainer container -* 8) Flush the threadlocal for the PortalContainer -* -*/ -public void sessionDestroyed(HttpSessionEvent event) { -try { -String portalContainerName = event.getSession().getServletContext().getServletContextName() ; -log.warn("Destroy session from " + portalContainerName + " portal"); -RootContainer rootContainer = RootContainer.getInstance() ; -PortalContainer portalContainer = rootContainer.getPortalContainer(portalContainerName) ; -PortalContainer.setInstance(portalContainer); -WebAppController controller = -(WebAppController)portalContainer.getComponentInstanceOfType(WebAppController.class) ; -PortalApplication portalApp = controller.getApplication(PortalApplication.PORTAL_APPLICATION_ID) ; -portalApp.getStateManager().expire(event.getSession().getId(), portalApp) ; -WindowInfosContainer.removeInstance(portalContainer, event.getSession().getId()); -} catch(Exception ex) { -log.error("Error while destroying a portal session",ex); -} finally { -PortalContainer.setInstance(null) ; -} -} -</programlisting> - --> <section id="sect-Reference_Guide-Portal_Life_cycle-The_Command_Servlet"> + <section id="sect-Reference_Guide-Portal_Life_cycle-The_Command_Servlet"> <title>The Command Servlet</title> <para> The CommandServlet is called by the portlet container for requests to particular portlets, it also includes some <literal>init</literal> code when the portal is launched. This servlet (<literal>org.gatein.wci.api.GateInServlet</literal>) is automatically added during the deployment of each portlet application and mapped to <literal>/gateinservlet</literal>.