[gatein-commits] gatein SVN: r1773 - portal/trunk/docs/reference-guide/en/modules.

Author: smumford Date: 2010-02-18 01:47:16 -0500 (Thu, 18 Feb 2010) New Revision: 1773 Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml Log: Edits to SSO.xml Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-02-18 06:47:03 UTC (rev 1772) +++ portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-02-18 06:47:16 UTC (rev 1773) @@ -6,7 +6,7 @@ <section id="sect-Reference_Guide-Single_Sign_On-Overview"> <title>Overview</title> <para> - &PRODUCT;, as an integration and aggregation platform provides some form of Single Sign On (<literal>SSO</literal>). + &PRODUCT;, provides some form of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. </para> <para> When logging into the portal users gain access to many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. There are many different Identity Management solutions available. In most cases each SSO framework provides a unique way to plug into a Java EE application. @@ -20,7 +20,7 @@ All the packages required for setup can be found in a zip file located at: <filename>http://repository.jboss.org/maven2/org/gatein/sso/sso-packagi... </para> <para> - When manipulating <filename>gatein.ear</filename> directly it is better to not run any portal extensions that could override the data. + Users are advised to not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly. </para> <para> Remove <literal>$JBOSS_HOME/server/default/deploy/gatein-sample-extension.ear</literal> and <literal>$JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear</literal> which are packaged by default with &PRODUCT;. @@ -40,36 +40,39 @@ <section id="sect-Reference_Guide-CAS_Central_Authentication_Service-CAS_server"> <title>CAS server</title> <para> - First we will set up the server to authenticate against the portal login module. You can find more information about setting up the server by reading the official CAS documentation, here we will install the CAS server on Tomcat + First, set up the server to authenticate against the portal login module. In this example the CAS server will be installed on Tomcat. </para> <section id="sect-Reference_Guide-CAS_server-Obtaining_CAS"> <title>Obtaining CAS</title> <para> - You can download CAS from http://www.jasig.org/cas/download. + CAS can be downloaded from <ulink type="http" url="http://www.jasig.org/cas/download">http://www.jasig.org...;. </para> <para> - Once downloaded extract it in what we will call $CAS_HOME from now. + Extract the downloaded file into a suitable location. This location will be referred to as <literal>$CAS_HOME</literal> in the following example. </para> </section> <section id="sect-Reference_Guide-CAS_server-Modifying_CAS_server"> <title>Modifying CAS server</title> <para> - To simplify we will directly modify the sources so that the produced web archive is configured the way we want. + To configure the web archive as desired, it is simpler to directly modify the sources. </para> <para> - First we will want to change the authenticaton handler to use the portal authentication handler: + To change the authentication handler to use the portal authentication handler: </para> <para> - The CAS Server Plugin makes secure authentication callbacks to a RESTful service installed on the remote GateIn server in order to authenticate a user. In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <emphasis>cas.war/WEB-INF/deployerConfigContext.xml </emphasis> file. + The CAS Server Plugin makes secure authentication callbacks to a RESTful service installed on the remote GateIn server in order to authenticate a user. </para> - <orderedlist> - <listitem> + <para> + In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>cas.war/WEB-INF/deployerConfigContext.xml </filename> file. + </para> + <procedure> + <step> <para> - Open $CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml + Open <filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</filename> </para> - </listitem> - <listitem> + </step> + <step> <para> Replace: <programlisting> &#60;!-- @@ -99,10 +102,10 @@ &#60;/property&#62; </programlisting> </para> - </listitem> - <listitem> + </step> + <step> <para> - With the following (Make sure to set the host, port and context with the values corresponding to your portal). Also available in $GATEIN_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml + With the following (Make sure to set the host, port and context with the values corresponding to your portal). Also available in <filename>GATEIN_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>. </para> <para> @@ -141,59 +144,64 @@ &#60;/property&#62; </programlisting> </para> - </listitem> - <listitem> + </step> + <step> <para> - Copy $GATEIN_SSO/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar and $GATEIN_SSO/cas/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar into the newly created directory $CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib + Copy <filename>GATEIN_SSO/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar</filename> and <filename>GATEIN_SSO/cas/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename> into the <filename>CAS_HOME/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory. </para> - </listitem> - <listitem> + </step> + <step> <para> - Get an installation of Tomcat and extract it in what we will call $TOMCAT_HOME. Change the default port to avoid a conflict with the default GateIn (for testing purposes). Edit $TOMCAT_HOME/conf/server.xml and replace the 8080 port to 8888. + Get an installation of Tomcat and extract it into a suitable location (which will be called <filename>TOMCAT_HOME</filename> for these instructions). + </para> + <para> + Change the default port to avoid a conflict with the default &PRODUCT; (for testing purposes). Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and replace the 8080 port to 8888. <note> <para> - If you are running GateIn with Tomcat on the same machine you will also need to change the port 8005 to something else to avoid port conflicts. + If &PRODUCT; is running with Tomcat on the same machine the port 8005 should be changed to something else to avoid port conflicts. </para> </note> </para> - </listitem> - <listitem> + </step> + <step> <para> - Go to $CAS_HOME/cas-server-webapp and do &#39;mvn install&#39; + Go to <filename>CAS_HOME/cas-server-webapp</filename> and execute the command: +<programlisting>mvn install +</programlisting> </para> - </listitem> - <listitem> + </step> + <step> <para> - Copy $CAS_HOME/cas-server-webapp/target/cas.war into $TOMCAT_HOME/webapps + Copy <filename>CAS_HOME/cas-server-webapp/target/cas.war</filename> into <filename>TOMCAT_HOME/webapps</filename>. </para> <para> - Now you should be able to start Tomcat and access http://localhost:8888/cas but at this stage you won&#39;t be able to login. + Tomcat should start and be accessible at <ulink type="http" url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>. Note that at this stage login won't be available. </para> <mediaobject> <imageobject> <imagedata fileref="images/cas.png" format="PNG" width="444" /> </imageobject> </mediaobject> - </listitem> - </orderedlist> + </step> + </procedure> </section> </section> <section id="sect-Reference_Guide-CAS_Central_Authentication_Service-Setup_the_CAS_client"> <title>Setup the CAS client</title> - <orderedlist> - <listitem> + <procedure> + <step> <para> - Copy all libraries from $GATEIN_SSO/cas/gatein.ear/lib into $JBOSS_HOME/server/default/deploy/gatein.ear/lib (Or if you are running GateIn in Tomcat, in $GATEIN_HOME/lib) + Copy all libraries from <filename>GATEIN_SSO/cas/gatein.ear/lib</filename> into <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or in Tomcat, into $<filename>GATEIN_HOME/lib</filename>) </para> - </listitem> - <listitem> - <para> - In JBoss AS, edit gatein.ear/META-INF/gatein-jboss-beans.xml and uncomment this section - </para> - <para> - + </step> + <step> + <itemizedlist> + <listitem> + <para> + In JBoss AS, edit <filename>gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> <programlisting>&#60;authentication&#62; &#60;login-module code=&#34;org.gatein.sso.agent.login.SSOLoginModule&#34; flag=&#34;required&#34;&#62; &#60;/login-module&#62; @@ -203,35 +211,51 @@ &#60;/login-module&#62; &#60;/authentication&#62; </programlisting> - </para> - <para> - If you are running GateIn in Tomcat, edit $GATEIN_HOME/conf/jaas.conf and uncomment this section - </para> - <para> - + + </listitem> + <listitem> + <para> + In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename> and uncomment this section: + </para> <programlisting>org.gatein.sso.agent.login.SSOLoginModule required org.exoplatform.services.security.j2ee.JbossLoginModule required portalContainerName=portal realmName=gatein-domain </programlisting> - At this point, you can test the installation, start GateIn (assuming that the CAS server using Tomcat is still running) by going to http://localhost:8888/cas you should be able to login with username &#39;root&#39; and password &#39;gtn&#39; or any account created through the portal. + </listitem> + </itemizedlist> + </step> + <step> + <para> + The installation can be tested at this point: </para> - </listitem> - </orderedlist> + <procedure> + <step> + <para> + Access &PRODUCT; (if the CAS server using Tomcat is still running) by going to <ulink type="http" url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>. + </para> + </step> + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> (or any account created through the portal). + </para> + </step> + </procedure> + </step> + </procedure> </section> - <section id="sect-Reference_Guide-CAS_Central_Authentication_Service-Setup_the_portal_to_redirect_to_CAS"> - <title>Setup the portal to redirect to CAS</title> + <section id="sect-Reference_Guide-CAS_Central_Authentication_Service-Redirect_to_CAS"> + <title>Redirect to CAS</title> <para> - Now we want to tell GateIn to redirect all user authentication to the CAS server. + To utilize the Central Authentication Service, &PRODUCT; needs to redirect all user authentication to the CAS server. </para> <para> - The CAS server can be located anywhere on the Internet, and this information must be properly configured within the GateIn instance. This configuration needs to be done in 3 files + Information about where the CAS is hosted must be properly configured within the &PRODUCT; instance. The required configuration is done in three files: <itemizedlist> <listitem> - <emphasis>In gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl replace the javascript at the bottom by:</emphasis> <para> - + In the <filename>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename> file replace the javascript code at the end with: <programlisting>&#60;script&#62; &#60;%=uicomponent.event(&#34;Close&#34;);%&#62; window.location = &#39;http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic&#39;; @@ -240,8 +264,9 @@ </para> </listitem> <listitem> - <emphasis>In gatein.ear/02portal.war/login/jsp/login.jsp replace everything by:</emphasis> <para> + Replace the contents of the <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> file with: + <programlisting>&#60;html&#62; &#60;head&#62; @@ -256,9 +281,8 @@ </para> </listitem> <listitem> - <emphasis>In gatein.ear/02portal.war/WEB-INF/web.xml replace the InitiateLoginServlet declaration by:</emphasis> <para> - + Replace the <literal>InitiateLoginServlet</literal> declaration in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> with: <programlisting>&#60;servlet&#62; &#60;servlet-name&#62;InitiateLoginServlet&#60;/servlet-name&#62; &#60;servlet-class&#62;org.gatein.sso.agent.GenericSSOAgent&#60;/servlet-class&#62; @@ -273,7 +297,7 @@ </itemizedlist> </para> <para> - From now on, all links redirecting to the user authentication pages will redirect to the CAS centralized authentication form. + Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form. </para> </section> @@ -282,76 +306,102 @@ <section id="sect-Reference_Guide-Single_Sign_On-JOSSO"> <title>JOSSO</title> <para> - This Single Sign On plugin enables seamless integration between GateIn Portal and the JOSSO Single Sign On Framework. Details about OpenSSO can be found <ulink url="http://www.ja-sig.org/products/cas/">here.</ulink> + This Single Sign On plugin enables seamless integration between &PRODUCT; and the JOSSO Single Sign On Framework. Details about OpenSSO can be found <ulink url="http://www.ja-sig.org/products/cas/">here</ulink>;. </para> <para> - The integration consitsts in two parts, the first part consists of installing or configuring a JOSSO server, the second part consists of setting up the portal to use the JOSSO server. + Setting up this integration happens in two distinct actions. The first part is installing or configuring a JOSSO server and the second involves setting up the portal to use the JOSSO server. </para> <section id="sect-Reference_Guide-JOSSO-JOSSO_server"> <title>JOSSO server</title> <para> - First we will set up the server to authenticate against the portal login module. You can find more information about setting up the server by reading the official JOSSO documentation, here we will install the JOSSO server on Tomcat + This section details setting up the JOSSO server to authenticate against the &PRODUCT; login module. </para> + <para> + In this example the JOSSO server will be installed on Tomcat. + </para> <section id="sect-Reference_Guide-JOSSO_server-Obtaining_JOSSO"> <title>Obtaining JOSSO</title> <para> - You can download JOSSO from http://sourceforge.net/projects/josso/files/ We will use the package that embeds Apache Tomcat. + JOSSO can be downloaded from <ulink type="http" url="http://sourceforge.net/projects/josso/files/">http://so...;. Use the package that embeds Apache Tomcat. </para> <para> - Once downloaded extract it in what we will call $JOSSO_HOME from now. + Once downloaded, extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. </para> </section> <section id="sect-Reference_Guide-JOSSO_server-Modifying_JOSSO_server"> <title>Modifying JOSSO server</title> - <orderedlist> - <listitem> + <procedure> + <step> <para> - Copy the files from $GATEIN_SSO/josso/plugin into the Tomcat directory ($JOSSO_HOME). + Copy the files from <filename>GATEIN_SSO/josso/plugin</filename> into the Tomcat directory (<filename>JOSSO_HOME</filename>). </para> <para> - It should replace or add $JOSSO_HOME/lib/josso-gateway-config.xml $JOSSO_HOME/lib/josso-gateway-gatein-stores.xml $JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties and add required jars into $JOSSO_HOME/webapps/josso/WEB-INF/lib + This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: </para> - </listitem> - <listitem> + <itemizedlist> + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> + </para> + </listitem> + <listitem> + <para> + <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> + </para> + </listitem> + </itemizedlist> <para> - Change the default Tomcat ports to avoid a conflict with the default GateIn (for testing purposes). Edit $TOMCAT_HOME/conf/server.xml and replace the 8080 port to 8888. + and + </para> + <itemizedlist> + <listitem> + <para> + <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> + </para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and replace the 8080 port to 8888 to change the default Tomcat port and avoid a conflict with the default &PRODUCT; port (for testing purposes). <note> + <title>Port Conflicts</title> <para> - If you are running GateIn with Tomcat on the same machine you will also need to change other ports to something else to avoid port conflicts. + If &PRODUCT; is being on a machine with Tomcat, other ports will need to be changed to avoid conflicts. </para> </note> </para> - </listitem> - <listitem> + </step> + <step> <para> - Now you should be able to start Tomcat and access http://localhost:8888/josso/signon/login.do but at this stage you won&#39;t be able to login. + Tomcat should now start and allow access to <ulink type="http" url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink> but at this stage login will not be available. </para> <mediaobject> <imageobject> <imagedata fileref="images/opensso.png" format="PNG" width="444" /> </imageobject> </mediaobject> - </listitem> - </orderedlist> + </step> + </procedure> </section> </section> <section id="sect-Reference_Guide-JOSSO-Setup_the_JOSSO_client"> <title>Setup the JOSSO client</title> - <orderedlist> - <listitem> + <procedure> + <step> <para> - Copy the libs from $GATEIN_SS)/josso/gatein.ear/lib into gatein.ear/lib (Or if you are running GateIn in Tomcat, in $GATEIN_HOME/lib) + Copy the library files from <filename>GATEIN_SS)/josso/gatein.ear/lib</filename> into <filename>gatein.ear/lib</filename> (Or into <filename>GATEIN_HOME/lib</filename> if &PRODUCT; is running in Tomcat) </para> - </listitem> - <listitem> - <para> - In JBoss AS, edit gatein.ear/META-INF/gatein-jboss-beans.xml and uncomment this section - </para> - <para> - + </step> + <step> + <itemizedlist> + <listitem> + <para> + In JBoss AS, edit <filename>gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> <programlisting>&#60;authentication&#62; &#60;login-module code=&#34;org.gatein.sso.agent.login.SSOLoginModule&#34; flag=&#34;required&#34;&#62; &#60;/login-module&#62; @@ -361,21 +411,37 @@ &#60;/login-module&#62; &#60;/authentication&#62; </programlisting> - </para> - <para> - If you are running GateIn in Tomcat, edit $GATEIN_HOME/conf/jaas.conf and uncomment this section - </para> - <para> - + </listitem> + <listitem> + <para> + In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename> and uncomment this section: + </para> <programlisting>org.gatein.sso.agent.login.SSOLoginModule required org.exoplatform.services.security.j2ee.JbossLoginModule required portalContainerName=portal realmName=gatein-domain </programlisting> - At this point, you can test the installation, start GateIn (assuming that the JOSSO server using Tomcat is still running) by going to http://localhost:8888/josso/signon/login.do you should be able to login with username &#39;root&#39; and password &#39;gtn&#39; or any account created through the portal. + </listitem> + </itemizedlist> + </step> + <step> + <para> + The installation can be tested at this point. </para> - </listitem> - </orderedlist> + <procedure> + <step> + <para> + Start &PRODUCT; (assuming that the JOSSO server using Tomcat is running) by going to <ulink type="http" url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>. + </para> + </step> + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. + </para> + </step> + </procedure> + </step> + </procedure> </section> <section id="sect-Reference_Guide-JOSSO-Setup_the_portal_to_redirect_to_JOSSO"> @@ -387,8 +453,9 @@ The CAS server can be located anywhere on the Internet, and this information must be properly configured within the GateIn instance. This configuration needs to be done in 3 files <itemizedlist> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl replace the javascript at the bottom by:</emphasis> - <para> + <programlisting>&#60;script&#62; &#60;%=uicomponent.event(&#34;Close&#34;);%&#62; @@ -398,8 +465,9 @@ </para> </listitem> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/login/jsp/login.jsp replace everything by:</emphasis> - <para> + <programlisting>&#60;html&#62; &#60;head&#62; @@ -414,8 +482,9 @@ </para> </listitem> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/WEB-INF/web.xml replace the InitiateLoginServlet declaration by:</emphasis> - <para> + <programlisting>&#60;servlet&#62; &#60;servlet-name&#62;InitiateLoginServlet&#60;/servlet-name&#62; @@ -588,8 +657,9 @@ The OpenSSO server can be located anywhere on the Internet, and this information must be properly configured within the GateIn instance. This configuration needs to be done in 3 files <itemizedlist> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl replace the javascript at the bottom by:</emphasis> - <para> + <programlisting>&#60;script&#62; &#60;%=uicomponent.event(&#34;Close&#34;);%&#62; @@ -599,8 +669,9 @@ </para> </listitem> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/login/jsp/login.jsp replace everything by:</emphasis> - <para> + <programlisting>&#60;html&#62; &#60;head&#62; @@ -615,8 +686,9 @@ </para> </listitem> <listitem> + <para> <emphasis>In gatein.ear/02portal.war/WEB-INF/web.xml replace the InitiateLoginServlet declaration by:</emphasis> - <para> + <programlisting>&#60;servlet&#62; &#60;servlet-name&#62;InitiateLoginServlet&#60;/servlet-name&#62;