Author: mstruk Date: 2010-03-28 18:07:55 -0400 (Sun, 28 Mar 2010) New Revision: 2377 Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml Log: Reference guide edits - Chapter 3 - SSO Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-03-28 16:47:47 UTC (rev 2376) +++ portal/trunk/docs/reference-guide/en/modules/SSO.xml 2010-03-28 22:07:55 UTC (rev 2377) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Single_Sign_On-Overview"> <title>Overview</title> <para> - &PRODUCT;, provides some form of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. + &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. @@ -19,7 +19,7 @@ In this tutorial, the SSO server is installed in a Tomcat installation. Tomcat can be obtained from <ulink type="http" url="http://tomcat.apache.org">http://tomcat.apache.org</ulink>. </para> <para> - 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...;. In this document we will call $SSO_HOME the directory where the file is extracted. + All the packages required for setup can be found in a zip file located at: <ulink type="http" url="http://repository.jboss.org/maven2/org/gatein/sso/sso-packaging...;. In this document we will call the directory where the file is extracted $GATEIN_SSO_HOME. </para> <para> Users are advised to not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly. @@ -57,10 +57,16 @@ <section id="sect-Reference_Guide-CAS_server-Modifying_CAS_server"> <title>Modifying CAS server</title> <para> - To configure the web archive as desired, it is simpler to directly modify the sources. + To configure the web archive as desired, the simplest way is to make the necessary changes directly in CAS codebase. </para> + <note> + <para> + To complete these instructions, and perform the final build step, you will need the Apache Maven 2. + You can get it <ulink type="http" url="http://maven.apache.org/download.html">here</ulink>;. + </para> + </note> <para> - To change the authentication handler to use the portal authentication handler: + First, we need to change the default authentication handler with the one provided by &PRODUCT;. </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. @@ -107,7 +113,7 @@ </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 <filename>GATEIN_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>. + 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_HOME/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>. </para> <para> @@ -149,7 +155,7 @@ </step> <step> <para> - 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. + Copy <filename>GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/sso-cas-plugin-&#60;VERSION&#62;.jar</filename> and <filename>GATEIN_SSO_HOME/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> </step> <step> @@ -160,7 +166,8 @@ 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 &PRODUCT; is running with Tomcat on the same machine the port 8005 should be changed to something else to avoid port conflicts. + If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. + They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. </para> </note> </para> @@ -195,7 +202,7 @@ <procedure> <step> <para> - 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>) + Copy all libraries from <filename>GATEIN_SSO_HOME/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> </step> <step> @@ -234,7 +241,7 @@ <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>. + Start (or restart) &PRODUCT;, and (assuming the CAS server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/cas">http://localhost:8888/cas</ulink>. </para> </step> <step> @@ -308,10 +315,10 @@ <section id="sect-Reference_Guide-Single_Sign_On-JOSSO"> <title>JOSSO</title> <para> - 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>;. + This Single Sign On plugin enables seamless integration between &PRODUCT; and the JOSSO Single Sign On Framework. Details about JOSSO can be found <ulink url="http://www.josso.org">here</ulink>. </para> <para> - 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. + Setting up this integration involves two steps. The first step is to install or configure a JOSSO server, and the second is to set up the portal to use the JOSSO server. </para> <section id="sect-Reference_Guide-JOSSO-JOSSO_server"> <title>JOSSO server</title> @@ -324,7 +331,7 @@ <section id="sect-Reference_Guide-JOSSO_server-Obtaining_JOSSO"> <title>Obtaining JOSSO</title> <para> - JOSSO can be downloaded from <ulink type="http" url="http://sourceforge.net/projects/josso/files/">http://so...;. 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. The integration was tested with JOSSO-1.8.1. </para> <para> Once downloaded, extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. @@ -336,7 +343,7 @@ <procedure> <step> <para> - Copy the files from <filename>GATEIN_SSO/josso/plugin</filename> into the Tomcat directory (<filename>JOSSO_HOME</filename>). + Copy the files from <filename>GATEIN_SSO_HOME/josso/plugin</filename> into the Tomcat directory (<filename>JOSSO_HOME</filename>). </para> <para> This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: @@ -370,7 +377,8 @@ <note> <title>Port Conflicts</title> <para> - If &PRODUCT; is being on a machine with Tomcat, other ports will need to be changed to avoid conflicts. + If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. + They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. </para> </note> </para> @@ -395,9 +403,14 @@ <procedure> <step> <para> - 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) + Copy the library files from <filename>GATEIN_SSO_HOME/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> </step> + <step> + <para> + Copy the file <filename>GATEIN_SSO_HOME/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> into <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> (or into <filename>GATEIN_HOME/webapps/portal.war/WEB-INF/classes</filename>, or <filename>GATEIN_HOME/conf</filename> if &PRODUCT; is running in Tomcat) + </para> + </step> <step> <itemizedlist> <listitem> @@ -433,7 +446,7 @@ <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>. + Start (or restart) &PRODUCT;, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/josso/signon/login.do">http://localhost:8888/josso/signon/login.do</ulink>. </para> </step> <step> @@ -489,7 +502,7 @@ &#60;servlet-class&#62;org.gatein.sso.agent.GenericSSOAgent&#60;/servlet-class&#62; &#60;init-param&#62; &#60;param-name&#62;ssoServerUrl&#60;/param-name&#62; - &#60;param-value&#62;http://localhost:8888/cas&#60;/param-value&#62; + &#60;param-value&#62;http://localhost:8888/josso/signon/login.do&#60;/param-value&#62; &#60;/init-param&#62; &#60;/servlet&#62; </programlisting> @@ -514,15 +527,15 @@ This Single Sign On plugin enables seamless integration between &PRODUCT; and the OpenSSO Single Sign On Framework. Details about OpenSSO can be found <ulink url="https://opensso.dev.java.net/">here</ulink>;. </para> <para> - Setting up this integration happens in two distinct actions. The first part is installing or configuring an OpenSSO server and the second involves setting up the portal to use the OpenSSO server. + Setting up this integration involves two steps. The first step is to install or configure an OpenSSO server, and the second is to set up the portal to use the OpenSSO server. </para> <section id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-OpenSSO_server"> <title>OpenSSO server</title> <para> - This section details setting up the OpenSSO server to authenticate against the Enterprise Portal Platform login module. + This section details the setting up of OpenSSO server to authenticate against the &PRODUCT; login module. </para> <para> - In this example the JOSSO server will be installed on Tomcat. + In this example the OpenSSO server will be installed on Tomcat. </para> <section id="sect-Reference_Guide-OpenSSO_server-Obtaining_OpenSSO"> <title>Obtaining OpenSSO</title> @@ -559,7 +572,8 @@ Change the default port to avoid a conflict with the default &PRODUCT; port (for testing purposes). Do this by editing <filename>TOMCAT_HOME/conf/server.xml</filename> and replacing the 8080 port to 8888. <note> <para> - If &PRODUCT; is running on the same machine as Tomcat, the port 8005 will also need to be changed to avoid port conflicts. + If &PRODUCT; is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. + They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. </para> </note> </para> @@ -593,14 +607,15 @@ </step> <step> <para> - Copy <filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&#60;VERSION&#62;.jar</filename>, <filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename>, and <filename>GATEIN_SSO/opensso/plugin/WEB-INF/lib/commons-logging-&#60;VERSION&#62;.jar</filename> into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>. + Copy <filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&#60;VERSION&#62;.jar</filename>, <filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-httpclient-&#60;VERSION&#62;.jar</filename>, and <filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/lib/commons-logging-&#60;VERSION&#62;.jar</filename> into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>. </para> </step> <step> <para> - Copy <filename>GATEIN_SSO/opensso/plugin/WEB-INF/classes/gatein.properties</filename> into <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> + Copy <filename>GATEIN_SSO_HOME/opensso/plugin/WEB-INF/classes/gatein.properties</filename> into <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> </para> </step> + <step> <para> Tomcat should start and be able to access <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein">http://localhost:8888/opensso/UI/Login?realm=gatein</ulink>. Login will not be available at this point. @@ -611,9 +626,54 @@ </imageobject> </mediaobject> </step> - </procedure> - </section> + </procedure> + <para>Configure "gatein" realm:</para> + <procedure> + <step> + <para>Direct your browser to <ulink type="http" url="http://localhost:8888/opensso">http://localhost:8888/opensso</ulink></para> + </step> + <step> + <para>Create default configuration</para> + </step> + <step> + <para>Login as <literal>amadmin</literal> and then go to tab "Configuration" -> tab "Authentication" -> link "Core" -> + add new value and fill in the class name "org.gatein.sso.opensso.plugin.AuthenticationPlugin". + This step is really important. Without it AuthenticationPlugin is not available among other OpenSSO authentication modules. + </para> + </step> + <step> + <para>Go to tab "Access control" and create new realm called "gatein".</para> + </step> + <step> + <para>Go to "gatein" realm and click on "Authentication" tab. At the bottom in the section "Authentication chaining" click on "ldapService". + Here change the selection from "Datastore", which is the default module in the authentication chain, to "AuthenticationPlugin". + This enables authentication of "gatein" realm by using GateIn REST service instead of the OpenSSO LDAP server.</para> + </step> + <step> + <para> + Go to "Advanced properties" and change UserProfile from "Required" to "Dynamic". This step is needed + because &PRODUCT; users are not in OpenSSO Datastore (LDAP server), so their profiles can't be obtained + if "Required" is active. By using "Dynamic" all new users are automatically + created in OpenSSO datastore after successful authentication. + </para> + </step> + <step> + <para> + Increase the user privileges to allow REST access. Go to "Access control" -> + Top level realm -> "Privileges" tab -> All authenticated users, and check the last two checkboxes: + <itemizedlist> + <listitem><para>Read and write access only for policy properties</para></listitem> + <listitem><para>Read and write access to all realm and policy properties</para></listitem> + </itemizedlist> + </para> + </step> + <step> + <para>Do the same for "gatein" realm.</para> + </step> + </procedure> + <para>TODO: The above OpenSSO manual configuration could be replaced by configuration files prepared in advance</para> + </section> </section> <section id="sect-Reference_Guide-OpenSSO_The_Open_Web_SSO_project-Setup_the_OpenSSO_client"> @@ -621,7 +681,7 @@ <procedure> <step> <para> - Copy all libraries from <filename>GATEIN_SSO/opensso/gatein.ear/lib</filename> into <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> (Or, in Tomcat, into <filename>GATEIN_HOME/lib</filename>) + Copy all libraries from <filename>GATEIN_SSO_HOME/opensso/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> </step> <step>