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

Author: ppenicka Date: 2013-02-01 10:13:00 -0500 (Fri, 01 Feb 2013) New Revision: 9110 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml Log: BZ#856450 - Implemented all JOSSO review comments from Tomas K. Ready for verification. 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 2013-02-01 00:18:07 UTC (rev 9109) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-02-01 15:13:00 UTC (rev 9110) @@ -8,6 +8,20 @@ <simpara> <revhistory> <revision> + <revnumber>6.0.0-45</revnumber> + <date>Fri Feb 01 2013</date> + <author> + <firstname>Petr</firstname> + <surname>Penicka</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#856450 - Implemented all JOSSO review comments from Tomas K. Ready for verification.</member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-44</revnumber> <date>Wed Jan 30 2013</date> <author> 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 2013-02-01 00:18:07 UTC (rev 9109) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2013-02-01 15:13:00 UTC (rev 9110) @@ -558,26 +558,23 @@ </section> </section> <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> - <title><remark>BZ#856430</remark>Java Open Single Sign-On Project (JOSSO)</title> + <title><remark>BZ#856430</remark>Java Open Single Sign-On (JOSSO)</title> <para> - Configuring JOSSO for JBoss Enterprise Application Platform requires an Apache server instance to host JOSSO. JBoss Enterprise Application Platform communicates with the JOSSO Apache instance through the single sign-on plug-in. + Java Open Single Sign-On (JOSSO) is an open-source single sign-on solution based on Java EE. It allows multiple web servers or web applications to authenticate users with a credential store. Detailed information about JOSSO can be found at <ulink url="http://www.josso.org"/>. + </para> + <para> + JOSSO integration with JBoss Portal Platform requires an Apache Tomcat server instance to host JOSSO. JBoss Portal Platform communicates with the JOSSO server through a single sign-on plug-in. + </para> + <para> + Setting up the integration consists of two steps &ndash; setting up the JOSSO server and setting up the portal to use the JOSSO server. These two steps differ depending on the used version of JOSSO, as described in <xref linkend="sect-JOSSO-1.8" /> and <xref linkend="sect-JOSSO-2.2" />. After completing the procedures described in either section, all links redirecting to user authentication pages will redirect to the JOSSO centralized authentication form. </para> - <para> - This single sign-on plug-in enables seamless integration between JBoss Portal Platform and the Java Open Single Sign-On (JOSSO) framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"/> . - </para> - <para> - The procedures in this section detail setting up the JOSSO server to authenticate against the JBoss Portal Platform login module. - </para> - <para> - After completing the procedures in this section, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. - </para> - <section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project-Auth_Process"> <title>Authentication Process</title> <para> - The login workflow for JOSSO is quite similar to that used for CAS authentications (specific details can be found in <xref linkend="sect-CAS-Authentication_Process"/>). + The login workflow for JOSSO is quite similar to that used for CAS authentication (specific details can be found in <xref linkend="sect-CAS-Authentication_Process"/>). </para> <para> - Briefly; when a user clicks to sign in to a portal they are redirected to the JOSSO login screen, where they supply the appropriate credentials. They are then redirected (with access authorization) back to the Portal. + Briefly &ndash; when a user clicks to sign in to a portal they are redirected to the JOSSO login screen, where they supply the appropriate credentials. They are then redirected (with access authorization) back to the Portal. </para> <para> The <systemitem>JOSSOAgent</systemitem> component performs a validation of the authorization ticket with the JOSSO server via a back channel after the <systemitem>InitiateLoginFilter</systemitem> has delegated the <parameter>josso_assertion_id</parameter> request to it. The JOSSO agent and JOSSO server communicate via web services. @@ -592,7 +589,7 @@ While the authentication plug-in (which is able to send REST requests to the portal, receive the response, and authenticate the user on the JOSSO side) is supported, this support is only for JOSSO 1.8 (not JOSSO 2.2 as at this release). </para> <para> - In this section, we will assume that JBoss Portal Platform will be running on JBoss Enterprise Application Platform 6 using port <emphasis role="italics">localhost:8080</emphasis> and that the JOSSO server will be running on Tomcat, using <emphasis role="italics">localhost:8888</emphasis>. + In this section, we will assume that JBoss Portal Platform will be running on JBoss Enterprise Application Platform 6 using <emphasis role="italics">localhost:8080</emphasis> and that the JOSSO server will be running on Tomcat, using <emphasis role="italics">localhost:8888</emphasis>. </para> <note> <para> @@ -600,17 +597,13 @@ </para> </note> </section> - <section> + <section id="sect-JOSSO-1.8"> <title>JOSSO 1.8</title> <section id="sid-55477376_JOSSO-ObtainingJOSSO"> <title>Obtaining JOSSO</title> <para> - JOSSO can be downloaded from <ulink url="http://sourceforge.net/projects/josso/files/"/>;. Use the package that embeds Apache Tomcat. + JOSSO can be downloaded from <ulink url="http://sourceforge.net/projects/josso/files/"/>;. Use any 1.8.z version in a package that embeds Apache Tomcat. Once downloaded, extract the package into what will be called <replaceable>JOSSO_HOME</replaceable> in this example. </para> - <remark>Docs Note; JOSSO versions up to 1.8.7 are available from this URL. I assume any after 1.8.2 are unsupported. Should we call this out in the docs?</remark> - <para> - Once downloaded, extract the package into what will be called <replaceable>JOSSO_HOME</replaceable> in this example. - </para> </section> <section id="sid-55477376_JOSSO-JOSSOserver"> <title>Setting up the JOSSO Server</title> @@ -620,34 +613,37 @@ <procedure> <step> <para> - <emphasis role="bold">Optional:</emphasis> To use the SSO authentication plug-in with JOSSO (not-mandatory but recommended. See <xref linkend="sect-CAS-Authentication_Process"/> for details): + <emphasis role="bold">Optional:</emphasis> To use the SSO authentication plug-in with JOSSO (not mandatory but recommended, see <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project-Auth_Process"/> for details): </para> <substeps> <step> <para> - Copy the files from <filename>SSO_HOME/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/</filename> into <replaceable>JOSSO_HOME</replaceable> directory, as shown below: - </para> - <para> - Keep in mind that <replaceable>SSO_HOME</replaceable> refers to the JOSSO directory within JBoss Portal Platform as mentioned in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>. + Copy the contents of the <filename>JPP_DIST/gatein-sso/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/</filename> directory into the <replaceable>JOSSO_HOME</replaceable> directory. Among the files that will be copied, the following ones are the most important: </para> <itemizedlist> <listitem> <para> - Copy <filename><replaceable>SSO_HOME</replaceable>/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/lib/josso-gateway-config.xml</filename> to <filename><replaceable>JOSSO_HOME</replaceable>/lib/josso-gateway-config.xml</filename>. The original file is being replaced. You should consider creating a backup of it before adding the new file. - </para> + <filename><replaceable>JOSSO_HOME</replaceable>/lib/josso-gateway-config.xml</filename> + </para> + <para> + The original file is being replaced. You should consider creating a backup of it before adding the new file. + </para> </listitem> <listitem> <para> - Add <filename><replaceable>SSO_HOME</replaceable>/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/lib/josso-gateway-config.xml</filename> to <filename><replaceable>JOSSO_HOME</replaceable>/lib/</filename>. This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. - </para> + <filename><replaceable>JOSSO_HOME</replaceable>/lib/josso-gateway-gatein-stores.xml</filename> + </para> + <para> + This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. + </para> </listitem> <listitem> <para> - Add <filename>SSO_HOME/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/webapps/josso/WEB-INF/classes/gatein.properties</filename> to <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/</filename>. This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. - </para> - <para> - This file may need to be reconfigured according to your JBoss Portal Platform environment (you need to use the host and port of your JBoss Portal Platform instance as this will be used by the Authentication plug-in to send REST requests over HTTP). - </para> + <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> + </para> + <para> + This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. You may need to edit the file and change the host and port to match your JBoss Portal Platform instance. The values will be used by the authentication plug-in when sending REST requests over HTTP. + </para> </listitem> </itemizedlist> </step> @@ -762,18 +758,18 @@ </para> </section> </section> - <section> + <section id="sect-JOSSO-2.2"> <title>JOSSO 2.2</title> <para> JOSSO 2.2 takes a different approach to SSO than JOSSO 1.8. It is designed to allow users to create their own SSO environment by modelling it in a flash web application called <emphasis role="strong">atricore-console</emphasis>. </para> <para> - Unfortunately this make it more difficult to use the SSO Authentication plug-in as it is not easily possible to configure an existing JOSSO 2.2 environment via Spring XML files. Using the <systemitem>AuthenticationPlugin</systemitem> with JOSSO 2.2 is not supported. + Unfortunately, this makes it more difficult to use the SSO Authentication plug-in as it is not easily possible to configure an existing JOSSO 2.2 environment via Spring XML files. Using the <systemitem>AuthenticationPlugin</systemitem> with JOSSO 2.2 is not supported. </para> <section id="sid-55477376_JOSSO-JOSSO2.2serversetup"> <title>JOSSO 2.2 Server Setup</title> <para> - You can downloaded JOSSO 2.2.0 from <ulink url="http://www.josso.org">JOSSO site</ulink> and follow the instructions from the JOSSO 2 quickstart in <ulink url="http://www.josso.org/confluence/display/JOSSO1/JOSSO2+Quick+sta... . + You can download JOSSO 2.2.0 from <ulink url="http://www.josso.org">JOSSO site</ulink> and follow the instructions from the JOSSO 2 quickstart in <ulink url="http://www.josso.org/confluence/display/JOSSO1/JOSSO2+Quick+sta... . </para> <para> After unzipping the download and running the JOSSO, you can access the <application>atricore</application> console at <uri>http://<replaceable>server.local.network</replaceable>:8081/atricore-console</uri> (<replaceable>server.local.network</replaceable> is the virtual host defined in <filename>/etc/hosts</filename>). @@ -882,11 +878,8 @@ </step> <step> <para> - Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">SP1EE</emphasis> via an <emphasis role="italics">Activation</emphasis> connection. + Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">SP1EE</emphasis> via an <emphasis role="italics">Activation</emphasis> connection. All parameters of the connection can keep their default values, with the exception of the <guilabel>Partner application location</guilabel> parameter, whose value needs to be changed to <ulink url="http://localhost:8080/portal"/>. </para> - <para> - <remark>Docs note: I don&apos;t even know what this sentence is trying to say.</remark> Left default values of parameters instead of parameter <emphasis role="italics">Partner application location</emphasis> needs to be configured to <ulink url="http://localhost:8080/portal"/> - </para> </step> <step> <para> @@ -972,22 +965,20 @@ </substeps> </step> <step> + <para>Test the configuration:</para> <substeps> <step> <para> Start the Portal. - </para> + </para> + </step> + <step> <para> - Access <uri>http://localhost:8080/portal</uri> and click <emphasis role="italics">Sign in</emphasis>. - </para> - <para> - You will be redirected to the JOSSO instance, but you will need to login with the username/password account created via the JOSSO console (for example <literal>john</literal>/<literal>password</literal>) as REST callbacks are not supported. - </para> - <para> - After a successful login to JOSSO, you will be redirected to the Portal as <literal>john</literal>. - </para> + Access <uri>http://localhost:8080/portal</uri> and click <emphasis role="italics">Sign in</emphasis>. You will be redirected to the JOSSO instance, but you will need to login with the username and password created via the JOSSO console (for example <literal>john</literal>/<literal>password</literal>) as REST callbacks are not supported. + </para> </step> </substeps> + <para>After a successful login to JOSSO, you will be redirected to the portal authenticated as <literal>john</literal>.</para> </step> </procedure> </section>