Author: thomas.heute(a)jboss.com Date: 2009-12-09 08:07:58 -0500 (Wed, 09 Dec 2009) New Revision: 980 Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml Log: More cleanup/fix Modified: portal/trunk/docs/reference-guide/en/modules/SSO.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/SSO.xml 2009-12-09 12:27:57 UTC (rev 979) +++ portal/trunk/docs/reference-guide/en/modules/SSO.xml 2009-12-09 13:07:58 UTC (rev 980) @@ -1,102 +1,100 @@ -<!-- - - Copyright (C) 2009 eXo Platform SAS. - - This is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as - published by the Free Software Foundation; either version 2.1 of - the License, or (at your option) any later version. - - This software is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this software; if not, write to the Free - Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - 02110-1301 USA, or see the FSF site: http://www.fsf.org. - ---> - <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/sgml/4.4/docbookx.dtd"> <chapter> -<title>Single Sign On</title> - + <title>Single Sign On</title> + <section> - <title>Overview of SSO</title> - <para>Portal as an integration and aggregation platform provides some form of SSO by itself. When you log into - the portal you gain access to many systems through portlets using a single identity. Still in many cases you - need to integrate the portal infrastructure with other SSO enabled systems. There are many different Identity Management - solutions on the market. In most cases each SSO framework provides its own way to plug into Java EE application. - </para> + <title>Overview of SSO</title> + <para>Portal as an integration and aggregation platform provides + some form of SSO by itself. When you log into + the portal you gain access to many systems through portlets using a + single identity. Still in many cases you + need to integrate the portal infrastructure with other SSO enabled + systems. There are many different Identity Management + solutions on the market. In most cases each SSO framework provides its own way + to plug into Java EE application. + </para> </section> - + <section> <title>CAS - Central Authentication Service</title> - <para>This Single Sign On plugin enables seamless integration between GateIn Portal and the CAS Single Sign On Framework. - Details about CAS can be found <ulink url="http://www.ja-sig.org/products/cas/">here</ulink> + <para> + This Single Sign On plugin enables seamless integration between + GateIn Portal and the CAS Single Sign On Framework. + Details + about CAS can be found + <ulink url="http://www.ja-sig.org/products/cas/">here</ulink> </para> <section> <title>Integration</title> <section> - <title>From source</title> - <itemizedlist> - <listitem> - <para> - Check out the GateIn SSO component from SVN using the following command: - <programlisting> + <title>From source</title> + <itemizedlist> + <listitem> + <para> + Check out the GateIn SSO component from SVN using + the following command: + <programlisting> <![CDATA[ svn co http://anonsvn.jboss.org/repos/gatein/components/sso/tags/<appropriate sso component version> ]]> - </programlisting> - </para> - </listitem> - <listitem> - <para> - Update <emphasis>packaging/profiles.xml</emphasis> to reflect the directories where your local JBoss AS 5.1.0.GA and Tomcat 6.0.2 are installed - </para> - </listitem> - </itemizedlist> + </programlisting> + </para> + </listitem> + <listitem> + <para> + Update + <emphasis>packaging/profiles.xml</emphasis> + to reflect the directories where your local JBoss + AS 5.1.0.GA and Tomcat 6.0.2 are installed + </para> + </listitem> + </itemizedlist> </section> <section> - <title>Install CAS plugin into a designated CAS (3.3.4) server</title> - <itemizedlist> - <listitem> - <para> - <programlisting> + <title>Install CAS plugin into a designated CAS (3.3.4) + server</title> + <itemizedlist> + <listitem> + <para> + <programlisting> <![CDATA[ mvn -Pplugin-cas-install install ]]> - </programlisting> - </para> - </listitem> - </itemizedlist> + </programlisting> + </para> + </listitem> + </itemizedlist> </section> <section> - <title>Install CAS GateIn Agent into the designated GateIn server</title> - <itemizedlist> - <listitem> - <para> - <programlisting> + <title>Install CAS GateIn Agent into the designated GateIn + server</title> + <itemizedlist> + <listitem> + <para> + <programlisting> <![CDATA[ mvn -Pgatein-cas-install install ]]> - </programlisting> - </para> - </listitem> - </itemizedlist> + </programlisting> + </para> + </listitem> + </itemizedlist> </section> </section> <section> - <title>CAS Server Plugin Configuration</title> - <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. - </para> - <para> - <programlisting> + <title>CAS Server Plugin Configuration</title> + <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. + </para> + <para> + <programlisting> <![CDATA[ <!-- Note: Modify the Plugin Configuration based on the actual information of a GateIn instance. @@ -108,32 +106,36 @@ <property name="gateInContext"><value>portal</value></property> </bean> ]]> - </programlisting> - </para> + </programlisting> + </para> </section> <section> - <title>GateIn Agent Configuration</title> - <para> - In a Single Sign On usecase, the GateIn server re-directs all "private" resource requests to the CAS server for authentication first. 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> - <emphasis>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</emphasis> - <para> - <programlisting> + <title>GateIn Agent Configuration</title> + <para> + In a Single Sign On usecase, the GateIn server re-directs + all "private" resource requests to the CAS server for + authentication first. 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> + <emphasis>gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</emphasis> + <para> + <programlisting> <![CDATA[ <script> <%=uicomponent.event("Close");%> window.location = 'http://localhost:8888/cas/login?service=http://localhost:8080/portal/private/classic'; </script> ]]> - </programlisting> - </para> - </listitem> - <listitem> - <emphasis>gatein.ear/02portal.war/login/jsp/login.jsp</emphasis> - <para> - <programlisting> + </programlisting> + </para> + </listitem> + <listitem> + <emphasis>gatein.ear/02portal.war/login/jsp/login.jsp</emphasis> + <para> + <programlisting> <![CDATA[ <html> <head> @@ -145,13 +147,13 @@ </body> </html> ]]> - </programlisting> - </para> - </listitem> - <listitem> - <emphasis>gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> - <para> - <programlisting> + </programlisting> + </para> + </listitem> + <listitem> + <emphasis>gatein.ear/02portal.war/WEB-INF/web.xml</emphasis> + <para> + <programlisting> <![CDATA[ <servlet> <servlet-name>InitiateLoginServlet</servlet-name> @@ -162,12 +164,12 @@ </init-param> </servlet> ]]> - </programlisting> - </para> - </listitem> - </itemizedlist> - </para> - - </section> - </section> + </programlisting> + </para> + </listitem> + </itemizedlist> + </para> + + </section> + </section> </chapter> \ No newline at end of file Modified: portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml 2009-12-09 12:27:57 UTC (rev 979) +++ portal/trunk/docs/reference-guide/en/modules/gadgets/Gadgets.xml 2009-12-09 13:07:58 UTC (rev 980) @@ -2,138 +2,129 @@ <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <section id="sect-Reference_Guide-Gadgets"> - <!-- - - Copyright (C) 2009 eXo Platform SAS. - - This is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as - published by the Free Software Foundation; either version 2.1 of - the License, or (at your option) any later version. - - This software is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this software; if not, write to the Free - Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - 02110-1301 USA, or see the FSF site: http://www.fsf.org. - - --><title>Gadgets</title> - <section id="sect-Reference_Guide-Gadgets-Overview"> - <title>Overview</title> - <para> - An gadget is a mini web application running on a platform and you can put it in a web page. This is a small application that helps users to do some private actions. + <title>Gadgets</title> + <section id="sect-Reference_Guide-Gadgets-Overview"> + <title>Overview</title> + <para> + An gadget is a mini web application running on a platform and you can + put it in a web page. This is a small application that helps + users to do some private actions. </para> - <para> - GateIn Portal supports some gadgets such as: Todo gadget, Calendar gadget, Calculator gadget, Weather Forecasts, RSS Reader gadget. + <para> + GateIn Portal supports some gadgets such as: Todo gadget, Calendar gadget, + Calculator gadget, Weather Forecasts, RSS Reader gadget. </para> - <itemizedlist> - <listitem> - <para> - Todo: This mini - application helps you to organize your day and work group. + <itemizedlist> + <listitem> + <para> + Todo: This mini - application helps you to organize your day and work + group. </para> - </listitem> - <listitem> - <para> - Calendar: A cool calendar to keep track of date in style. + </listitem> + <listitem> + <para> + Calendar: A cool calendar to keep track of date in style. </para> - </listitem> - <listitem> - <para> - Calculator: This is the coolest calculator for your page. + </listitem> + <listitem> + <para> + Calculator: This is the coolest calculator for your page. </para> - </listitem> - <listitem> - <para> - RSS Reader: This gadget lets you het a sneak preview of your favourite feeds around web + </listitem> + <listitem> + <para> + RSS Reader: This gadget lets you het a sneak preview of your favourite + feeds around web </para> - </listitem> - <listitem> - <para> - Weather Forecasts: This gadget notifies you of current weather condition and gives tomorrow's forecast. + </listitem> + <listitem> + <para> + Weather Forecasts: This gadget notifies you of current weather condition + and gives tomorrow's forecast. </para> - </listitem> - </itemizedlist> - </section> + </listitem> + </itemizedlist> + </section> - <section id="sect-Reference_Guide-Gadgets-Existing_Gadgets"> - <title>Existing Gadgets</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Liste.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <section id="sect-Reference_Guide-Gadgets-Existing_Gadgets"> + <title>Existing Gadgets</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Liste.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Create_a_new_Gadget"> - <title>Create a new Gadget</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/New.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <section id="sect-Reference_Guide-Gadgets-Create_a_new_Gadget"> + <title>Create a new Gadget</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/New.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Remote_Gadget"> - <title>Remote Gadget</title> - <para> - This is the reference to a remote gadget (stock one). + <section id="sect-Reference_Guide-Gadgets-Remote_Gadget"> + <title>Remote Gadget</title> + <para> + This is the reference to a remote gadget (stock one). </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/Import.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <mediaobject> + <imageobject> + <imagedata fileref="images/Import.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Gadget_Importing"> - <title>Gadget Importing</title> - <para> - After referencing the gadget successfully, then import it into the local repository. + <section id="sect-Reference_Guide-Gadgets-Gadget_Importing"> + <title>Gadget Importing</title> + <para> + After referencing the gadget successfully, then import it into the local + repository. </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/Imported.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <mediaobject> + <imageobject> + <imagedata fileref="images/Imported.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Gadget_Web_Editing"> - <title>Gadget Web Editing</title> - <para> - Edit it from the Web the imported Gadget to modify it: + <section id="sect-Reference_Guide-Gadgets-Gadget_Web_Editing"> + <title>Gadget Web Editing</title> + <para> + Edit it from the Web the imported Gadget to modify it: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/EditImportedOnline.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <mediaobject> + <imageobject> + <imagedata fileref="images/EditImportedOnline.png" + format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Gadget_IDE_Editing"> - <title>Gadget IDE Editing</title> - <para> - Edit it from your IDE thanks to the WebDAV protocol: + <section id="sect-Reference_Guide-Gadgets-Gadget_IDE_Editing"> + <title>Gadget IDE Editing</title> + <para> + Edit it from your IDE thanks to the WebDAV protocol: </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/EditImportedWebDAV.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <mediaobject> + <imageobject> + <imagedata fileref="images/EditImportedWebDAV.png" + format="PNG" /> + </imageobject> + </mediaobject> + </section> - <section id="sect-Reference_Guide-Gadgets-Dashboard_Viewing"> - <title>Dashboard Viewing</title> - <para> - View it from the Dashboard when you drag and drop the Gadget from listing to the dashboard. + <section id="sect-Reference_Guide-Gadgets-Dashboard_Viewing"> + <title>Dashboard Viewing</title> + <para> + View it from the Dashboard when you drag and drop the Gadget from listing + to the dashboard. </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/Dashboard.png" format="PNG" /> - </imageobject> - </mediaobject> - </section> + <mediaobject> + <imageobject> + <imagedata fileref="images/Dashboard.png" format="PNG" /> + </imageobject> + </mediaobject> + </section> </section> Modified: portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml =================================================================== --- portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml 2009-12-09 12:27:57 UTC (rev 979) +++ portal/trunk/docs/reference-guide/en/modules/gadgets/Setup_a_Gadget_Server.xml 2009-12-09 13:07:58 UTC (rev 980) @@ -2,65 +2,98 @@ <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <section id="sect-Reference_Guide-Setup_a_Gadget_Server"> - <!-- - - Copyright (C) 2009 eXo Platform SAS. - - This is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as - published by the Free Software Foundation; either version 2.1 of - the License, or (at your option) any later version. - - This software is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public - License along with this software; if not, write to the Free - Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - 02110-1301 USA, or see the FSF site: http://www.fsf.org. - - --><title>Setup a Gadget Server</title> - <section id="sect-Reference_Guide-Setup_a_Gadget_Server-Setup_virtual_servers_for_the_gadget_rendering"> - <title>Setup virtual servers for the gadget rendering</title> - <para> - GateIn recommend you to setup 2 different virtual hosts because it's the basis of the security model of gadgets. Having the gadget running on a different domain than the container (the website that 'contains' the app), the gadget can't read / modify / do anything nasty to GateIn Portal (like adding spam messages, stealing your cookies, whatever). + <title>Setup a Gadget Server</title> + <section + id="sect-Reference_Guide-Setup_a_Gadget_Server-Setup_virtual_servers_for_the_gadget_rendering"> + <title>Setup virtual servers for the gadget rendering</title> + <para> + GateIn recommend you to setup 2 different virtual hosts + because it's the + basis of the security model of gadgets. Having + the gadget + running on a different domain than the container (the + website + that 'contains' the app), the gadget can't read / modify + / do + anything nasty to GateIn Portal (like adding spam messages, + stealing your cookies, whatever). </para> - <para> - For example you can server the portal from <emphasis role="bold">http://www.sample.com</emphasis> and the gadgets from <emphasis role="bold">http://www.samplemodules.com</emphasis> + <para> + For example you can server the portal from + <emphasis role="bold">http://www.sample.com</emphasis> + and the gadgets from + <emphasis role="bold">http://www.samplemodules.com</emphasis> + </para> + <para> + To do this, we need to configure a parameter with the name is + <emphasis>gadgets.hostName</emphasis> + , the value is the + <emphasis>path/to/gadgetServer</emphasis> + in GadgetRegisteryService service like following: + <programlisting><![CDATA[<component> + <key>org.exoplatform.application.gadget.GadgetRegistryService</key> + <type>org.exoplatform.application.gadget.jcr.GadgetRegistryServiceImpl</type> + <init-params> + <value-param> + <name>gadgets.hostName</name> + <description>Gadget server url</description> + <value>http://localhost:8080/GateInGadgetServer/gadgets/</value> + </value-param> + </init-params> +</component>]]></programlisting> + </para> + <para> + It's possible to have multiple rendering servers. That would + help to + balance the load across multiple servers. </para> - <para> - To do this, we need to configure a parameter with the name is <emphasis>gadgets.hostName</emphasis>, the value is the <emphasis>path/to/gadgetServer</emphasis> in GadgetRegisteryService service like following: -<programlisting> {code:xml} &lt;component&gt; &lt;key&gt;org.exoplatform.application.gadget.GadgetRegistryService&lt;/key&gt; &lt;type&gt;org.exoplatform.application.gadget.jcr.GadgetRegistryServiceImpl&lt;/type&gt; &lt;init-params&gt; &lt;value-param&gt; &lt;name&gt;gadgets.hostName&lt;/name&gt; &lt;description&gt;Gadget server url&lt;/description&gt; &lt;value&gt;http://localhost:8080/GateInGadgetServer/gadgets/&lt;/value&gt; &lt;/value-param&gt; &lt;/init-params&gt; &lt;/component&gt; {code}</programlisting> + <para> + If you still want to deploy it on the same server, make sure + that it + starts before anything that use the gadgets (for example + the + webapp GateInGadgets that use + org.exoplatform.application.gadget.GadgetRegister) </para> - <warning> - <title>Warning</title> - <para> - This has only been possible since Portal 2.6 - </para> - </warning> - <para> - It's possible to have multiple rendering servers. That would help to balance the load across multiple servers. + </section> + <section> + <title>Configuration</title> + <section> + <title>Security key</title> + <para> + A file + <emphasis role="bold">key.txt</emphasis> + has to be generated + <emphasis role="bold">for every installation of GateIn to + be + secure</emphasis> + . This file contains a secret key used to crypt the security + token used for authenticating the user. On Linux this can be + generated such as: + </para> + <programlisting>dd if=/dev/random bs=32 count=1 | openssl base64 &gt; /tmp/key.txt</programlisting> + </section> + <section> + <title>Gadget proxy and concat configuration</title> + <para>These servers have to be on the same domain as the gadget server. You can configure it in: <filename>eXoGadgetServer:/WEB-INF/classes/containers/default/container.js</filename>. +<programlisting><![CDATA["gadgets.content-rewrite" : { + "include-urls": ".*", + "exclude-urls": "", + "include-tags": ["link", "script", "embed", "img", "style"], + "expires": "86400", + "proxy-url": "http://localhost:8080/eXoGadgetServer/gadgets/proxy?url=", + "concat-url": "http://localhost:8080/eXoGadgetServer/gadgets/concat?" +},]]></programlisting> </para> - <para> - If you still want to deploy it on the same server, make sure that it starts before anything that use the gadgets (for example the webapp GateInGadgets that use org.exoplatform.application.gadget.GadgetRegister) - </para> - <para> - 1 Config 1.1 Security key A file <emphasis role="bold">key.txt</emphasis> has to be generated <emphasis role="bold">for every installation of GateIn to be secure</emphasis>. This file contains a secret key used to crypt the security token used for authenticating the user. in Tomcat this file is in nix command line will create an excellent key: - </para> - -<programlisting>dd if=/dev/random bs=32 count=1 | openssl base64 &gt; /tmp/key.txt -</programlisting> - <para> - 1.1 Gadget proxy and concat configuration These servers have to be on the same domain as the gadget server. You can configure it in: -<programlisting>{code} -{, "expires": "86400", "proxy-url": "http://localhost:8080/GateInGadgetServer/gadgets/proxy?url=", "concat-url": "http://localhost:8080/GateInGadgetServer/gadgets/concat?" -}{code}</programlisting> - </para> - <para> - 1.1 Proxy if your server is behind a proxy and you want to allow external gadgets, you should configure the proxy of your JVM adding this code at the begining. {code}-Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword {code} - </para> + </section> + <section> + <title>Proxy</title> + <para> + if your server is behind a proxy and you want to allow external gadgets, you should configure the proxy of your JVM adding this code at the begining. + </para> + <programlisting>-Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword</programlisting> + </section> + </section> </section>