Author: jaredmorgs Date: 2012-11-28 00:32:06 -0500 (Wed, 28 Nov 2012) New Revision: 8971 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml 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/eXoJCR.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gatein.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/external-value-storages.xml Log: BZ#856430 - Rebased the CAS section from the work done by Marek at https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml 2012-11-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Preface.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -17,44 +17,45 @@ <replaceable>JPP_DIST</replaceable> </term> <listitem> - <para>The installation root of the JBoss Enterprise Application Platform instance. This folder contains the main folders that comprise the server such as <filename>/jboss-as</filename>. + <para>The installation root of the JBoss Enterprise Application Platform instance. This folder contains the application server directory, as well as supplemental folders containing resources necessary for gatein-management and gatein-sso. that comprise the server such as <filename>/bin</filename>, <filename>/standalone</filename>, and <filename>/gatein</filename>. </para> - <para>For example, if the JBoss Portal Platform instance is deployed into the <filename>/opt/jboss/jboss-epp-&VY;/</filename> directory, the <replaceable>JPP_DIST</replaceable> directory is <filename>/opt/jboss/jboss-epp-&VY;</filename>. + <para>For example, if the JBoss Portal Platform binary is extracted to <filename>/opt/jboss/JPP/</filename> directory, the <replaceable>JPP_DIST</replaceable> directory is <filename>/opt/jboss/JPP</filename>. </para> </listitem> </varlistentry> <varlistentry> <term> - <replaceable>PORTAL_SSO</replaceable> + <replaceable>JPP_SERVER</replaceable> </term> <listitem> - <para>The zip file located in the <filename><filename>JPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Portal Platform binary package. Used throughout <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>.</para> + <para>The directory containing the application server, and the configuration files necessary to run JBoss Portal Platform.</para> + <para>This directory contains directories such as <filename>/bin</filename>, <filename>/standalone</filename>, and <filename>/gatein</filename>. +</para> + <para>Using the example in <replaceable>JPP_DIST</replaceable>, the <replaceable>JPP_SERVER</replaceable> directory is <filename>/opt/jboss/JPP/jboss-jpp-&VY;/</filename>. </para> </listitem> </varlistentry> <varlistentry> <term> - <replaceable>CAS_DIR</replaceable> + <replaceable>PORTAL_SSO</replaceable> </term> <listitem> - <para>The installation root of the Central Authentication Service (CAS) Single Sign-on Framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.</para> + <para>The directories and files located in the <filename><filename>JPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Portal Platform binary package. Used throughout <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>.</para> </listitem> </varlistentry> <varlistentry> <term> - <replaceable>HTTPD_DIST</replaceable> + <replaceable>CAS_DIR</replaceable> </term> <listitem> - <para>The installation root of the Apache httpd Server. This folder contains the main folders that comprise the server such as <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/bin</filename>.</para> + <para>The installation root of the Central Authentication Service (CAS) Single Sign-on Framework. This directory is an arbitrary location chosen when CAS is downloaded and installed.</para> </listitem> </varlistentry> <varlistentry> <term> - <replaceable>PROFILE</replaceable> + <replaceable>HTTPD_DIST</replaceable> </term> <listitem> - <para>The name of the server profile used as part of testing or production configuration. The server profiles reside in <filename>JPP_DIST/jboss-as/server</filename>.</para> - <para>For example, to use the <literal>default</literal> profile, replace the <replaceable>PROFILE</replaceable> text in the file path to read <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>default</replaceable>/</filename> - </para> + <para>The installation root of the Apache httpd Server. This folder contains the main folders that comprise the server such as <filename>/conf</filename>, <filename>/webapps</filename>, and <filename>/bin</filename>.</para> </listitem> </varlistentry> </variablelist> 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-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -8,6 +8,34 @@ <simpara> <revhistory> <revision> + <revnumber>6.0.0-20</revnumber> + <date>Wed Nov 28 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#856430 - Rebased the CAS section from the work done by Marek at https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... </member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>6.0.0-18</revnumber> + <date>Thu Nov 15 2012</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>BZ#876821 - Removed obsolete chapters and sections from the JCR part, according to the guidance in the ticket. </member> + </simplelist> + </revdescription> + </revision> + <revision> <revnumber>6.0.0-17</revnumber> <date>Mon Nov 5 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-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -36,7 +36,7 @@ </listitem> <listitem> <para> - Cluster authentication with loadbalancer or with JBoss SSO valve. Refer to <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/> for more information. + Cluster authentication with load balancer or with JBoss SSO valve. Refer to <xref linkend="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/> for more information. </para> </listitem> </itemizedlist> @@ -527,7 +527,7 @@ </para> </note> <para> - There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>). + There is also possibility for integration with JBoss clustered SSO valve (See <xref linkend="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>). </para> </section> <section id="sect-Authentication_Authorization_Intro-SSOLogin"> 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-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -5,13 +5,13 @@ ]> <chapter id="sect-Reference_Guide-SSO_Single_Sign_On"> <title>SSO - Single Sign On</title> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Overview"> + <section id="sect-SSO_Single_Sign_On_-Overview"> <title>Overview and Configuration Assumptions</title> <para> JBoss Portal Platform provides an implementation of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. </para> <para> - When logging into the portal users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. + When logging into the portal, users can access many systems through portlets using a single identity. In many cases, however, the portal infrastructure must be integrated with other SSO enabled systems. </para> <para> 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. @@ -22,7 +22,7 @@ <itemizedlist> <listitem> <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"/> + <xref linkend="sect-SSO_Single_Sign_On_-Central_Authentication_Service"/> </para> </listitem> <listitem> @@ -48,7 +48,7 @@ </para> </note> <para> - All the packages required for SSO setup can be found in a zip file located in the <filename><filename>JPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Portal Platform binary package. + All the packages required for SSO setup can be found in the <filename><filename>JPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Portal Platform binary package. </para> <para> In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. @@ -62,8 +62,9 @@ Remove <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-extension.ear</filename> and <filename>JBOSS_HOME/server/PROFILE/deploy/gatein-sample-portal.ear</filename> which are packaged by default with JBoss Enterprise Portal Platform. </para> --> </warning> </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> - <title>Enabling SSO using JBoss SSO Valve</title> + <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> + <title><remark>NEEDINFO</remark>Enabling SSO using JBoss SSO Valve</title> + <remark>Is the SSO valve still valid for JPP 6?</remark> <!-- Source Metadata URL: https://issues.jboss.org/browse/JBQA-4530 Author [w/email]: Marek Posolda (mposolda(a)redhat.com) @@ -102,6 +103,7 @@ </para> <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-SSO_Integration"> <title>SSO Integration</title> + <remark>The file paths in this procedure need to be verified if this procedure is to remain for JPP 6</remark> <step> <para> Open the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: @@ -156,6 +158,7 @@ </formalpara> <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> <title>Testing the SSO Valve</title> + <remark>The file paths in this procedure need to be verified if this procedure is to remain for JPP 6</remark> <step> <para> If you are using a Linux system, you can configure file <emphasis role="bold">/etc/hosts</emphasis> to contain these lines: @@ -223,6 +226,7 @@ </para> </step> </procedure> + <remark>The file paths in this procedure need to be verified if this procedure is to remain for JPP 6</remark> <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Enabling_SSO_with_Other_Web_Applications"> <title>Enabling SSO with Other Web Applications</title> <para> @@ -268,6 +272,7 @@ </formalpara> <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Test_SSO_Between_Portal_and_JMX_Console"> <title>Test SSO Between Portal and JMX Console</title> + <remark>The file paths in this procedure need to be verified if this procedure is to remain for JPP 6</remark> <step> <para> Start a portal instance on one node: @@ -300,6 +305,7 @@ </para> <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Redirect_to_Use_SSO_Valve_Authentication"> <title>Redirect to Use SSO Valve Authentication</title> + <remark>The file paths in this procedure need to be verified if this procedure is to remain for JPP 6</remark> <step> <para> Open the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: @@ -326,94 +332,314 @@ </step> </procedure> </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"> - <title>Central Authentication Service</title> - <para> - This Single Sign On plug-in enables seamless integration between JBoss Portal Platform and the Central Authentication Service (<emphasis role="bold">CAS</emphasis>) Single Sign On Framework. Details about CAS can be found <ulink url="http://www.ja-sig.org/cas/"> here </ulink> . - </para> - <para> - The integration consists of two parts; the first part consists of installing or configuring a CAS server, the second part consists of setting up the portal to use the CAS server. - </para> - <section> - <title>CAS_DIR</title> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-CAS_server"> - <title>Installing CAS server, and defining CAS_DIR</title> - <step> + <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 + <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> + <orderedlist> + <listitem> + <para>A user visits the main portal page, and wishes to authenticate. The user clicks + <emphasis role="italics">Sign in</emphasis>. </para> + </listitem> + <listitem> + <para>Normally this action would present the GateIn Portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as + <ulink url="http://localhost:8080/portal/sso"/>. + </para> + <para>The portal handles this user action by calling the interceptor (Servlet filter) + <emphasis role="strong">LoginRedirectFilter</emphasis>, which redirects the user seamlessly away from the + <emphasis role="italics">/portal/sso</emphasis> + URL to the CAS server page. + </para> + </listitem> + <listitem> + <para>The interceptor redirects the user to the CAS login page + <ulink url="http://localhost:8888/cas/login"/> + . The user enters the correct authentication information, and submits the form. +</para> + <para>The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with JBoss Portal Platform. Refer to <xref linkend="sect-CAS_Authentication_Plug-in"/> for specific details about this technology.</para> + <remark>Docs Note: Removed the large block of content here about the Authentication Plug-in into the Authentication Plug-in section. It just didn&apos;t fit in this work flow overview section, and sits much better in the plug-in section.</remark> + </listitem> + <listitem> + <para> Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as + <ulink url="http://localhost:8080/portal/initiatelogin"/> + . </para> + <para>The <emphasis role="strong">InitiateLoginFilter</emphasis> +interceptor acts on the user redirection to + <emphasis role="italics">/portal/initiatelogin</emphasis> +by obtaining a CAS ticket attached in the HTTP request inside the + <emphasis role="italics">ticket</emphasis> +parameter. The interceptor then delegates validation of this ticket to a configured + <emphasis role="strong">CASAgent</emphasis> + component. </para> + </listitem> + <listitem> + <para>The <emphasis>CASAgent</emphasis> validates the ticket by sending a validation request to the CAS server through a configured back channel. The CAS server validates the request, and ensures it contains the user name of the authenticated user in step 3. + </para> + </listitem> + <listitem> <para> - Set up the server to authenticate against the portal login module, as described in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>. - </para> - </step> - <step> + After SSO validation, + <emphasis role="italics">InitiateLoginFilter</emphasis> + redirects the user to the portal login URL + <ulink url="http://localhost:8080/portal/login"/> + , which initiates JAAS authentication. +</para> + <para>The <emphasis role="strong">SSOLoginModule</emphasis> detects whether the user has been successfully validated by + <emphasis role="italics">CASAgent</emphasis>. If this is the case, the login module obtains data about user (groups, memberships) from + <emphasis role="italics">OrganizationService</emphasis> + and encapsulates the details into an + <emphasis role="strong">Identity</emphasis> + object. </para> + </listitem> + <listitem> + <para>The + <emphasis role="strong">JBossAS7LoginModule</emphasis> completes the authentication request by establishing the JAAS + <emphasis role="italics">Subject</emphasis>, + 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). +</para> + </listitem> + <listitem> + <para>After successful JAAS authentication, the user is redirected to the portal in an authenticated state.</para> + </listitem> + </orderedlist> + <para>For more information about the available Login Modules shipped with the product, refer to the JBoss Enterprise Application Platform <citetitle>Security Guide</citetitle>. </para> + </section> + <section id="sect-CAS-Logout_Workflow"> + <title>Logout Process</title> + <para>The logout process with CAS integration occurs in the following order:</para> + <orderedlist> + <listitem> + <para>The authenticated user clicks the + <emphasis role="italics">Sign out</emphasis> + link. + </para> + </listitem> + <listitem> + <para>The + <emphasis role="strong">CASLogoutFilter</emphasis> +interceptor recognizes the logout request, and redirects the user to the CAS logout page + <ulink url="http://localhost:8888/cas/logout"/> +. </para> + </listitem> + <listitem> + <para>The + CAS server logs out the user, and invalidate the CAS cookie + <emphasis role="italics">CASTGC</emphasis> . </para> + </listitem> + <listitem> + <para>CAS redirects the user back to the portal using the logout redirection configured in <xref linkend="sect-CAS_Logout_Redirection"/> . + </para> + <para>If the <emphasis role="italics">CASLogoutFilter</emphasis> + is enabled, the user is logged out from both the portal and CAS server. + </para> + </listitem> + <listitem> <para> - Download CAS v3.5 from <ulink url="http://www.jasig.org/cas/download" type="http"/> . -This CAS version forms part of a supported configuration for &PRODUCT;. </para> - </step> - <step> - <para> - Extract the downloaded file into a suitable location. </para> - <para>This location is referred to as <replaceable>CAS_DIR</replaceable> in the following procedures. - </para> - </step> - </procedure> +The logout redirection request completes the logout process on the CAS server&apos;s side, and the user is redirected to the portal&apos;s anonymous page. </para> + </listitem> + </orderedlist> </section> - <section id="sect-CAS_HTTPD_DIST"> - <title><remark>BZ#856430</remark>HTTPD_DIST</title> - <task> - <title>Install Tomcat and change default ports for CAS compatibility.</title> - <tasksummary> - <para>Tomcat hosts CAS on the portal instance. Install and configure Tomcat before proceeding with other configuration relating to CAS. </para> - <para>This procedure covers the Linux installation method for Apache Tomcat (httpd). </para> - <para>Completing this task defines the file path abbreviation <filename>HTTPD_DIST</filename>, which is used in other CAS configuration procedures.</para> - </tasksummary> + <section id="sect-CAS-Configuration_Overview"> + <title>CAS Configuration Overview</title> + <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> + </listitem> + <listitem> + <para>The portal will listen on + <emphasis role="italics">localhost:8080</emphasis></para> + </listitem> + </itemizedlist> + <section id="sect-CAS-Install_Tomcat_Server"> + <title>Install Tomcat Server</title> + <para>Install and configure Apache Tomcat before proceeding with other configuration relating to CAS. +</para> + <para>This procedure covers the Linux installation method for Apache Tomcat (httpd). +Completing this task defines the file path abbreviation HTTPD_DIST, which is used in other CAS configuration procedures.</para> + <para>File name abbreviations in this section are described in <xref linkend="sect-File_Name_Conventions"/></para> <procedure> + <title>Configuring Tomcat for CAS</title> <step> - <para>Install Tomcat by running <command>sudo yum install httpd</command> in a terminal. - </para> + <para>Install Tomcat by running <command>sudo yum install httpd</command> in a terminal.</para> </step> <step> - <para> Edit <filename><replaceable>HTTPD_DIST</replaceable>/conf/httpd.conf</filename> and change the Listen 80 port to 8888 to avoid a conflict with the default JBoss Portal Platform. -<remark>NEEDINFO - this used to be HTTPD_DIST/conf/server.xml, but if you install httpd using RPM, this file doesn&apos;t seem to exist. I assumed the .conf file was the correct place to change the listen port.</remark> </para> + <para>Edit <filename>HTTPD_DIST/conf/httpd.conf</filename> and change the Listen 80 port to 8888 to avoid a conflict with the default JBoss Portal Platform listen port.</para> + <remark>NEEDINFO - this used to be HTTPD_DIST/conf/server.xml, but if you install httpd using RPM, this file doesn&apos;t seem to exist. I assumed the .conf file was the correct place to change the listen port.</remark> + </step> + <step> + <para>Ensure port 8888 is open in the server firewall, and the httpd service is enabled and running so the platform can communicate with Apache on the same server. +</para> + </step> + </procedure> + </section> + <section id="sect-CAS-Download_CAS"> + <title>Download CAS</title> + <para> + CAS can be downloaded from + <ulink url="http://www.jasig.org/cas/download"/> + . The supported version is + <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> + <para> + Extract the downloaded file into a suitable location on the Tomcat server. This location will be referred to as + <code>CAS_DIR</code> + in subsequent 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> + <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> + <remark>Docs Note: This section was originally in https://docs.jboss.org/author/display/GTNPORTAL35/Central+Authentication+... and has been reworked quite a bit to promote the authentication plug-in as the &quot;best&quot; solution.</remark> + <para>CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS <literal>AuthenticationPlugin</literal>. </para> + <para>Implementing the <literal>AuthenticationPlugin</literal> on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the <literal>AuthenticationPlugin</literal>. </para> + <para>The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal&apos;s own identity storage provided by the PicketLink IDM + <emphasis role="italics">OrganizationService</emphasis>. The <literal>AuthenticationPlugin</literal> receives the portal&apos;s response to the CAS server, and continues with the authentication process based on user data in the response. +</para> + <para>For the plug-in to function correctly, it must be properly configured on the CAS server to connect to this service. Set up the server to authenticate against the portal using the REST call-back.</para> + <procedure> + <title>Configuring the Authentication plug-in</title> + <step> + <para> + Open + <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</code> + . + </para> + </step> + <step> + <para>Replace the default configuration, which declares the Jasig <classname>SimpleTestUsernamePasswordAuthenticationHandler</classname> Authentication Handler with the following supported Authentication Handler. </para> <note> - <para> - If JBoss Portal Platform is running on the same machine as Apache Tomcat, other ports will need to be changed in addition to 8080 to avoid conflicts. They can be changed to any free port. For example; change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. - </para> + <para>This configuration is available in the + <code><replaceable>SSO_HOME</replaceable>/cas.war/WEB-INF/deployerConfigContext.xml</code>. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. </para> </note> + <programlisting> +&lt;!-- + XML comment used for configuration guidance removed for ease of readability+--&gt; +&lt;bean class=&quot;org.gatein.sso.cas.plugin.AuthenticationPlugin&quot;&gt; + &lt;property name=&quot;gateInProtocol&quot;&gt;&lt;value&gt;http&lt;/value&gt;&lt;/property&gt; + &lt;property name=&quot;gateInHost&quot;&gt;&lt;value&gt;localhost&lt;/value&gt;&lt;/property&gt; + &lt;property name=&quot;gateInPort&quot;&gt;&lt;value&gt;8080&lt;/value&gt;&lt;/property&gt; + &lt;property name=&quot;gateInContext&quot;&gt;&lt;value&gt;portal&lt;/value&gt;&lt;/property&gt; + &lt;property name=&quot;httpMethod&quot;&gt;&lt;value&gt;POST&lt;/value&gt;&lt;/property&gt; +&lt;/bean&gt; +</programlisting> </step> <step> - <para>Ensure port 8888 is open in the server firewall, and the httpd service is enabled and running so the platform can communicate with Apache on the same server. </para> + <para> + Copy all jars from + <code>SSO_HOME/cas/plugin/WEB-INF/lib/ </code>to the + <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/lib</code> directory. + </para> </step> </procedure> - </task> - </section> - <section> - <title><remark>BZ#856430</remark>Configure the platform</title> - <task> - <title>Configuring SSO configuration.properties for CAS</title> - <tasksummary> - <para>To prepare the portal platform for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, also needs to be specified.</para> - </tasksummary> - <taskprerequisites> - <itemizedlist> + </section> + <section id="sect-CAS_Logout_Redirection"> + <title>Logout redirection setup</title> + <para>The CAS server displays the CAS logout page with a link to return to the portal by default. To make the CAS server redirect to the portal page after a logout, modify + <code>CAS_DIR/cas-server-webapp/src/main/webapp/</code> + <code>WEB-INF/cas-servlet.xml</code> + to include the + <code>followServiceRedirects=&quot;true&quot;</code> + parameter: + </para> + <programlisting language="">&lt;bean id=&quot;logoutController&quot; class=&quot;org.jasig.cas.web.LogoutController&quot; + p:centralAuthenticationService-ref=&quot;centralAuthenticationService&quot; + p:logoutView=&quot;casLogoutView&quot; + p:warnCookieGenerator-ref=&quot;warnCookieGenerator&quot; + p:ticketGrantingTicketCookieGenerator-ref=&quot;ticketGrantingTicketCookieGenerator&quot; + p:followServiceRedirects=&quot;true&quot;/&gt; +</programlisting> + </section> + <section id="sect-CAS_SSO_Cookie_Configuration"> + <title>CAS SSO cookie configuration (CASTGC)</title> + <para>Jasic CAS uses a cookie named <firstterm>CAS Ticket Granting Cookie</firstterm> + (CASTGC) +to control the authentication state within the browser session. The cookie contains a Ticket Granting Ticket (TGT), which preserves SSO authentication where more than one site is controlled by the same SSO profile. </para> + <example id="exam-CASTGC_Authentication"> + <title>Basic CASTGC Portal Authentication Scenario </title> + <para>Two portal servers are provisioned that use a single CAS server to manage authentication. The portals are named <literal>accounts</literal> and <literal>services</literal>.</para> + <para>When a user initially accesses the <literal>accounts</literal> portal, they provide their SSO credentials, and CAS authenticates them as a registered user. The user then switches to the <literal>services</literal> portal, and is authenticated when she clicks the Sign in link. </para> + <para>This behavior is correct given this example because the browser instance stores the browser authentication state using the CASTCG cookie. The CASTCG cookie in this instance creates new ticket for the <literal>services</literal> portal automatically based on the authentication state present for the accounts portal. + </para> + </example> + <para>The behavior described in <xref linkend="exam-CASTGC_Authentication"/>exists through a secured connection only (https connection). To benefit from authentication across two or more portals, one of the options below must be implemented. Choose the correct option based on the deployment environment: </para> + <variablelist> + <varlistentry> + <term>Testing</term> <listitem> - <para> - Set up the server to authenticate against the portal login module, as described in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"/>. -<remark>&lt;-- NEEDINFO - 20121024 - need to check that this process is still valid and correct based on EPP 6 changes. </remark> </para> + <para>Alter the CASTGC cookie to be non-secure. </para> + <para>The cookie can be accessed through http (insecure) connections. </para> + <para>To configure this test behavior, open + <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml</code> + and switch the attribute + <code>cookieSecure</code> + to false. </para> + <programlisting>&lt;bean id=&quot;ticketGrantingTicketCookieGenerator&quot; + p:cookieSecure=&quot;false&quot; + p:cookieMaxAge=&quot;-1&quot; + p:cookieName=&quot;CASTGC&quot; + p:cookiePath=&quot;/cas&quot; /&gt;</programlisting> </listitem> + </varlistentry> + <varlistentry> + <term>Production</term> <listitem> - <para>Complete the task in <xref linkend="sect-CAS_HTTPD_DIST"/></para> + <para>Correctly implement the https protocol for all production servers that rely on CAS. This configuration is the recommended method for any production server, and ensures greater security for CAS connections. Refer to the Jasig documentation about securing CAS <ulink url="https://wiki.jasig.org/display/CASUM/Securing+Your+New+CAS+Server "/> for information and resources.</para> </listitem> - <listitem> - <para>The platform is configured to run on the default host and port (http://localhost:8080)</para> - </listitem> - </itemizedlist> - </taskprerequisites> + </varlistentry> + </variablelist> + </section> + </section> + <section id="sect-CAS-Modifying_the_Portal"> + <title>Modifying the Portal</title> + <section id="sect-CAS_Portal_SSO_Primary_Configuration_File"> + <title>Portal SSO Primary Configuration File</title> + <para> + The main GateIn Portal configuration file for SSO integration is + <code>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/conf/sso/security-sso-configuration.xml</code> + . All required SSO components such as agents and SSO interceptors (servlet filters in v5.x of the product) are configured in this file. </para> + <para>In most cases, it will never be necessary to edit <filename>security-sso-configuration.xml</filename> directly when using JBoss Portal Platform. The architecture in JBoss Enterprise Application Platform 6 means that users can override the base configuration described in this file using name/value pairs configured in one place: <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename></para> + <para>The exception to this rule is where configuration present in <filename>security-sso-configuration.xml</filename> is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor). </para> + </section> + <section id="sect-CAS_Configuring_the_Platform"> + <title>Portal configuration.properties for CAS SSO</title> + <para>To prepare the portal platform for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, also needs to be specified. +</para> <procedure> + <title>Configuring SSO configuration.properties for CAS</title> <step> - <para>Open <filename>JPP_DIST/standalone/configuration/gatein/configuration.properties</filename>, and locate the SSO sections in the file.</para> + <para>Open <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> and locate the SSO sections in the file.</para> </step> <step> - <para>Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. Ensure <replaceable> [portal.container.name]</replaceable> is replaced with the name of the portal container used in production.</para> - <programlisting># SSO + <para>Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. Ensure <replaceable>[portal.container.name]</replaceable> is replaced with the name of the portal container used in production.</para> + <programlisting> +# SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} gatein.sso.login.module.enabled=${gatein.sso.enabled} @@ -422,187 +648,101 @@ gatein.sso.portal.url=http://localhost:8080 gatein.sso.filter.logout.class=org.gatein.sso.agent.filter.CASLogoutFilter gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout -gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@&lt;replaceable&gt;[portal.container.name]&lt;/replaceable&gt;@(a)/initiatessologin&lt;/programlisting&gt; +gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@&lt;replaceable&gt;[portal.container.name]&lt;/replaceable&gt;@(a)/initiatessologin +</programlisting> </step> </procedure> - </task> - </section> - <section> - <title>Modify CAS Server</title> - <para> - The CAS Server Plug-in makes secure callbacks to a RESTful service installed on the remote &PRODUCT; server to authenticate a user. - </para> - <para> - In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is controlled by the <filename>cas.war/WEB-INF/deployerConfigContext.xml</filename> file. - </para> - <para> - Change the default authentication handler with the one provided by &PRODUCT;. - </para> - <para> -<remark>NEEDINFO - 20121024 - Will a customer need to use Maven to modify the CAS server, or are the files contained in GATEIN_SSO_HOME/cas/plugin/WEB-INF/lib/ </remark> To perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from <ulink url="http://maven.apache.org/download.html" type="http"> here </ulink> . + <variablelist> + <varlistentry> + <term>gatein.sso.enabled</term> + <listitem> + <para>Specifies whether SSO integration is enabled on the portal. With this option set to &quot;true&quot; when a user clicks the + <emphasis role="italics">Sign in</emphasis> + link, the user is redirected to the + <emphasis role="italics">/portal/sso</emphasis> + URL rather than a standard Sign in dialog. </para> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-Modifying_CAS_server"> - <title>Modifying CAS server</title> - <step> - <para> - Open <filename><replaceable>CAS_DIR</replaceable>/webapps/cas/WEB-INF/deployerConfigContext.xml</filename> - </para> - </step> - <step> - <para>Make the following changes to the directives in <filename>deployerConfigContext.xml</filename>.</para> - <programlisting>&lt;!--&lt;bean -class=&quot;org.jasig.cas.authentication.handler.support.SimpleTestUsernamePasswordAuthenticationHandler&quot; /&gt; ---&gt; -&lt;bean class=&quot;org.gatein.sso.cas.plugin.AuthenticationPlugin&quot;&gt; -&lt;property name=&quot;gateInProtocol&quot;&gt;&lt;value&gt;http&lt;/value&gt;&lt;/property&gt; - &lt;property name=&quot;gateInHost&quot;&gt;&lt;value&gt;localhost&lt;/value&gt;&lt;/property&gt; - &lt;property name=&quot;gateInPort&quot;&gt;&lt;value&gt;8080&lt;/value&gt;&lt;/property&gt; - &lt;property name=&quot;gateInContext&quot;&gt;&lt;value&gt;portal&lt;/value&gt;&lt;/property&gt; -&lt;property name=&quot;httpMethod&quot;&gt;&lt;value&gt;POST&lt;/value&gt;&lt;/property&gt; -&lt;/bean&gt;</programlisting> - </step> -<!--BZ#856430 - Removed these steps because they contain info not required according to instructions provided my Marek P in attachment.--><!--<step> - <para> - Replace this code: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default102.xml" parse="text"/></programlisting> - <para> - with the following (ensure you set the host, port and context with the values corresponding to your portal). The code is available for direct copy in the <filename>PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename> file: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default103.xml" parse="text"/></programlisting> -</step>--><!--<step> - <para> - Copy the following files into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> directory:</para> - <itemizedlist> - <listitem> - <para><filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-<replaceable>VERSION</replaceable>.jar</filename></para> - </listitem> - <listitem> - <para><filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-<replaceable>VERSION</replaceable>.jar</filename></para> - </listitem> - </itemizedlist> -</step>--><!--<step> - <para> - Navigate locally to the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp</filename> directory and execute the following command: - </para> - <programlisting>mvn install -</programlisting> -</step>--><!--<step> - <para> - Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>HTTPD_DIST/webapps</filename> directory. - </para> - <para> - Tomcat should start without issue and should be accessible at <ulink url="http://localhost:8888/cas" type="http"> http://localhost:8888/cas </ulink> . - </para> - <note> - <para> - At this stage the login functionality will not be available. - </para> - </note> - <mediaobject> - <imageobject> - <imagedata width="444" scale="100" fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG"/> - </imageobject> - </mediaobject> -</step>--> </procedure> - <note> - <para> - On logout, the CAS server will display the CAS logout page with a link to return to the portal. To make the CAS server redirect to the portal page after a logout, modify the <filename>cas.war/WEB-INF/cas-servlet.xml</filename> to include the follow line : + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.callback.enabled</term> + <listitem> + <para> +Specifies whether the REST callback authentication handler is enabled. </para> + <para>The handler is required if the CAS server must use the SSO Authentication plug-in to handle portal authentication. See <xref linkend="sect-CAS_Logout_Redirection"/> +for details. The callback handler is enabled by default. Set the parameter to false if the Authentication Plugin on the CAS server side is not required. </para> - <programlisting> -&lt;bean id=&quot;logoutController&quot; class=&quot;org.jasig.cas.web.LogoutController&quot; - p:centralAuthenticationService-ref=&quot;centralAuthenticationService&quot; - p:logoutView=&quot;casLogoutView&quot; - p:warnCookieGenerator-ref=&quot;warnCookieGenerator&quot; - p:ticketGrantingTicketCookieGenerator-ref=&quot;ticketGrantingTicketCookieGenerator&quot; - p:followServiceRedirects=&quot;true&quot;/&gt; -</programlisting> - </note> - </section> - <section> - <title>Configure CAS client</title> - <para><remark>NEEDINFO - this section will need to be reviewed to ensure it is still correct</remark></para> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-Setup_the_CAS_client"> - <title>Setup the CAS client</title> - <step> - <para> - Copy all the libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/cas/gatein.ear/lib</filename> directory into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/default/deploy/gatein.ear/lib</filename>) directory<remark>&lt;-- what are the new file paths?</remark>. - </para> - </step> - <step> - <para> - Edit the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file. In the file, first comment out or remove all &lt;login-module&gt; entries. Then uncomment the following section <remark>&lt;-- what are the new file paths?</remark>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default105.xml" parse="text"/></programlisting> -<!-- Removing as per https://issues.jboss.org/browse/JBEPP-1350 - <para> - In Tomcat, edit <filename>GATEIN_HOME/conf/jaas.conf</filename>, uncomment on this section and comment other parts: - </para> -<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; -org.exoplatform.services.security.j2ee.TomcatLoginModule required -portalContainerName=portal -realmName=gatein-domain; -</programlisting> - --> </step> - <step> - <para> - The installation can be tested at this point (assuming the CAS server on Tomcat is running): - </para> - <procedure> - <step> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.login.module.enabled</term> + <listitem> + <para>Specifies whether a pre-defined SSO login module declared in <filename> JPP_SERVER/standalone/configuration/standalone.xml</filename> is used for authentication. When the property is set to &quot;true&quot;, the SSODelegateLoginModule delegates work to another login module, as specified using the <property>gatein.sso.login.module.class</property> property. SSODelegateLoginModule will also resend all its options to its delegate.</para> + <para>This parameter removes the need to manually change any login module configuration in the standalone.xml file, which simplifies platform configuration. </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.login.module.class</term> + <listitem> + <para>Specifies the classname of the login module SSODelegateLoginModule will delegate to. This parameter will work only if gatein.sso.login.module.enabled is specified.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.server.url</term> + <listitem> <para> - Start (or restart) JBoss Portal Platform and direct your web browser to <ulink url="http://localhost:8888/cas" type="http"> http://localhost:8888/cas </ulink> . - </para> - </step> - <step> + Specifies the URL from which the CAS server is accessible. </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.portal.url</term> + <listitem> <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> (or any other account created through the portal). - </para> - </step> - </procedure> - </step> - </procedure> + Specifies the URL from which the JBoss Portal Platform is accessible. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.class</term> + <listitem> + <para> + Specifies the class of the logout filter. In the example above + <code>org.gatein.sso.agent.filter.CASLogoutFilter</code> +is the correct choice because this filter is able to redirect to the CAS server and perform logout on CAS side. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.url</term> + <listitem> + <para> + Specifies the CAS server logout URL, which is used for redirection by the logout filter + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.enabled</term> + <listitem> + <para>Optional parameter, which specifies whether the logout interceptor is enabled. To disable logout on CAS side, set the parameter value to &quot; + false&quot; + . This results in both options + <code>gatein.sso.filter.logout.class</code> + and + <code>gatein.sso.filter.logout.url</code> are ignored </para> + <para>When a user logs out of the portal, the CAS authentication ticket is still valid for other CAS authenticated sites. </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.login.sso.url</term> + <listitem> + <para> + Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page. + </para> + </listitem> + </varlistentry> + </variablelist> + </section> </section> - <section> - <title>Redirect to CAS</title> - <para><remark>NEEDINFO - this section will need to be reviewed to ensure it is still correct according to the changes in EPP 6</remark></para> - <para> - To utilize the Central Authentication Service, &PRODUCT; needs to redirect all user authentication to the CAS server. - </para> - <para> - Information about where the CAS is hosted must be properly configured within the &PRODUCT; instance. The required configuration is done by modifying three files. - </para> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-Redirect_to_CAS"> - <title>Redirect to CAS</title> - <step> - <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows <remark>&lt;-- what are the new file paths?</remark>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default106.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows <remark>&lt;-- what are the new file paths?</remark>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default107.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with <remark>&lt;-- what are the new file paths?</remark>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default108.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Add the following Filters at the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename> <remark>&lt;-- what are the new file paths?</remark>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default109.xml" parse="text"/></programlisting> - </step> - </procedure> - <para> - Once these changes have been made, all links to the user authentication pages will redirect to the CAS centralized authentication form and CAS can be used as an SSO implementation in the portal. - </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/eXoJCR/jcr/configuration/external-value-storages.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/external-value-storages.xml 2012-11-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/external-value-storages.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -1,202 +1,76 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-External_Value_Storages"> - <title>External Value Storages</title> - <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> - <title>Introduction</title> - <para> + <title>External Value Storages</title> + <section id="sect-Reference_Guide-External_Value_Storages-Introduction"> + <title>Introduction</title> + <para> JCR values are stored in the Workspace Data container by default. The eXo JCR offers an additional option of storing JCR values separately from the Workspace Data container which can help keep Binary Large Objects (BLOBs) separate. </para> - <!-- <para> +<!-- <para> Value storage configuration is a part of the repository configuration. Refer to <xref linkend="sect-Reference_Guide-JCR_configuration-Example_of_the_portal_system_workspace" /> for more details. - </para> --> <para> + </para> --> <para> Tree-based storage is recommended in most cases. </para> - <!-- Not sure this is necessary +<!-- Not sure this is necessary <para> If you run an application on Amazon EC2 - the S3 option may be interesting for architecture. Simple 'flat' storage is good in speed of creation/deletion of values, it might be a compromise for a small storages. -</para> --> - </section> - - <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> - <title>Tree File Value Storage</title> - <para> +</para> --> </section> + <section id="sect-Reference_Guide-External_Value_Storages-Tree_File_Value_Storage"> + <title>Tree File Value Storage</title> + <para> Tree File Value Storage holds values in tree-like file system files. <property>Path</property> property points to the root directory to store the files. </para> - <para> + <para> This is a recommended type of external storage because it can contain large amount of files limited only by disk/volume free space. </para> - <para> + <para> However, using Tree File Value Storage can result in a higher time on value deletion, due to the removal of unused tree-nodes. </para> -<example> -<title>Tree File Value Storage Configuration</title> -<programlisting language="XML" role="XML"><xi:include href="../../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <example> + <title>Tree File Value Storage Configuration</title> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default25.xml" parse="text"/></programlisting> + <para> Comment #1: The <emphasis role="bold">id</emphasis> is the value storage unique identifier, used for linking with properties stored in a workspace container. </para> - <para> + <para> Comment #2: the <emphasis role="bold">path</emphasis> is a location where value files will be stored. </para> -</example> - <para> + </example> + <para> Each file value storage can have the <function>filters</function> for incoming values. A filter can match values by <property>property-type</property>, <property>property-name</property>, <property>ancestor-path</property>. It can also match the size of values stored (<property>min-value-size</property>) in bytes. </para> - <para> + <para> In the previous example a filter with <property>property-type</property> and <property>min-value-size</property> has been used. This results in storage for binary values with size greater of 1MB. </para> - <para> + <para> It is recommended that properties with large values are stored in file value storage only. </para> - <para> + <para> The example below shows a value storage with different locations for large files (<property>min-value-size</property> a 20Mb-sized filter). </para> - <para> + <para> A value storage uses ORed logic in the process of filter selection. This means the first filter in the list will be called first and if it is not matched the next will be called, and so on. </para> - <para> - In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path "<literal>data/20Mvalues</literal>". All other filters will be stored in "<literal>data/values</literal>". + <para> + In this example a value matches the 20MB filter <property>min-value-size</property> and will be stored in the path &quot;<literal>data/20Mvalues</literal>&quot;. All other filters will be stored in &quot;<literal>data/values</literal>&quot;. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </section> - - <!-- <section id="sect-Reference_Guide-External_Value_Storages-Simple_File_Value_Storage"> -<title>Simple File Value Storage</title> -<note> -<para> -Not recommended to use in production due to low capacity capabilities on most file systems. -</para> -<para> -But if you're sure in your file-system or data amount is small it may be useful for you as haves a faster speed of Value removal. -</para> -</note> -<para> -Holds Values in flat file system files. <property>path</property> property points to root directory in order to store files -</para> -<programlisting language="Java" role="Java"><xi:include parse="text" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default27.java" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> -<programlisting>&lt;value-storage id="Storage #1" class="org.exoplatform.services.jcr.impl.storage.value.fs.SimpleFileValueStorage"&gt; -&lt;properties&gt; -&lt;property name="path" value="data/values"/&gt; -&lt;/properties&gt; -&lt;filters&gt; -&lt;filter property-type="Binary" min-value-size="1M"/&gt; -&lt;/filters&gt; -</programlisting> -</section> --> <section id="sect-Reference_Guide-External_Value_Storages-Content_Addressable_Value_storage_CAS_support"> - <title>Content Addressable Value storage (CAS) support</title> - <para> - eXo JCR supports the <phrase>Content-addressable storage</phrase> feature for <phrase>values</phrase> storing. - </para> - <para> - Content-addressable storage, also referred to as associative storage and abbreviated as <emphasis role="bold">CAS</emphasis>, is a mechanism for storing information that can be retrieved based on its content, not its storage location. - </para> - <para> - It is typically used for high-speed storage and retrieval of fixed content, such as documents stored for compliance with government regulations. - </para> - <para> - Content-addressable value storage stores unique content once. Different properties (values) with same content will be stored as one data file shared between those values. We can tell the value content will be shared across some values in storage and will be stored in one physical file. - </para> - <para> - Storage size will be decreased for applications which govern potentially same data in the content. - </para> - <para> - As an example; if 100 different properties contain the same data (mail attachments for example) the storage stores only one single file. The file will be shared with all referencing properties. - </para> - <para> - If a property value changes it is stored in an additional file. Alternatively the file is shared with other values, pointing to the same content. - </para> - <para> - The storage calculates value content address each time the property was changed. CAS write operations are more expensive compared to the non-CAS storages. - </para> - <para> - Content address calculation is based on <literal>java.security.MessageDigest</literal> hash computation and has been tested with MD5 and SHA1 algorithms. - </para> - <note> - <para> - CAS storage works most efficiently on data that does not change often. For data that changes frequently CAS is not as efficient as location-based addressing. - </para> - - </note> - <para> - CAS support can be enabled for <phrase>Tree</phrase> and <phrase>Simple File Value Storage</phrase> types. - </para> - <para> - To enable CAS support just configure it in the JCR Repositories configuration with other Value Storages. - </para> - -<programlisting language="XML" role="XML"><xi:include href="../../../../extras/Advanced_Development_JCR_external-value-storages/default28.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <variablelist id="vari-Reference_Guide-Content_Addressable_Value_storage_CAS_support-CAS_Properties"> - <title>CAS Properties</title> - <varlistentry> - <term>digest-algo</term> - <listitem> - <para> - Digest hash algorithm (MD5 and SHA1 were tested). - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>vcas-type</term> - <listitem> - <para> - Value CAS internal data type, JDBC backed is currently implemented: - </para> - <para> - <literal>org.exoplatform.services.jcr.impl.storage.value.cas.JDBCValueContentAddressStorageImpl</literal> - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>jdbc-source-name</term> - <listitem> - <para> - A <literal>JDBCValueContentAddressStorageImpl</literal> specific parameter, a database will be used to save CAS metadata. - </para> - - </listitem> - - </varlistentry> - <varlistentry> - <term>jdbc-dialect</term> - <listitem> - <para> - A <literal>DBCValueContentAddressStorageImpl</literal> specific parameter defining database dialect. - </para> - - </listitem> - - </varlistentry> - - </variablelist> - - </section> - - <section id="sect-Reference_Guide-External_Value_Storages-Disabling_value_storage"> - <title>Disabling value storage</title> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_external-value-storages/default26.xml" parse="text"/></programlisting> + </section> + <section id="sect-Reference_Guide-External_Value_Storages-Disabling_value_storage"> + <title>Disabling value storage</title> + <para> The JCR allows you to disable value storage by adding the following property into its configuration. </para> - -<programlisting language="XML">&lt;property name="enabled" value="false" /&gt;</programlisting> - <warning> - <title>Warning</title> - <para> + <programlisting language="XML">&lt;property name=&quot;enabled&quot; value=&quot;false&quot; /&gt;</programlisting> + <warning> + <title>Warning</title> + <para> It is recommended that this functionality be used for internal and testing purpose only, and with caution, as all stored values will be inaccessible. </para> - - </warning> - - </section> - - + </warning> + </section> </chapter> - Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gatein.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gatein.xml 2012-11-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr-with-gatein.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -1,10 +1,9 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY % BOOK_ENTITIES SYSTEM "Reference_Guide.ent"> %BOOK_ENTITIES; ]> <chapter id="chap-Reference_Guide-eXo_JCR_with_GateIn"> - <title>eXo JCR with GateIn</title> - <!-- <xi:include href="jcr-with-gtn/how-to-extend-my-gatein-instance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="jcr-with-gtn/managed-datasources-under-jboss-as.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <title>eXo JCR with GateIn</title> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="jcr-with-gtn/managed-datasources-under-jboss-as.xml"/> </chapter> - Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR.xml 2012-11-28 05:17:16 UTC (rev 8970) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR.xml 2012-11-28 05:32:06 UTC (rev 8971) @@ -13,15 +13,12 @@ <!-- <xi:include href="eXoJCR/jcr/configuration/configuration-persister.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/jdbc-data-container-config.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/external-value-storages.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/workspace-persistence-storage.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/configuration/rest-services-on-groovy.xml"/> <!-- cluster configs --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/cluster-config.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbosscache-configuration-templates.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/lock-manager-config.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/query-handler-config.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/jbossts-transaction-service.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/transaction-manager-lookup.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/repository-creation-service.xml"/> -<!-- search --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/jcr-query-usecases.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/jcr-query-usecases.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/searching-repository-content.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/searching/fulltext-search-and-settings.xml"/> <!-- api extensions --><!--<xi:include href="eXoJCR/jcr/api-extensions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--><!-- protocols --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/protocols/webdav.xml"/> @@ -30,15 +27,7 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/backup/backup-client.xml"/>--> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/backup/use-external-backup-tool.xml"/> <!-- other --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/statistics.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/repository-check-controller.xml"/> -<!--<xi:include href="eXoJCR/jcr/jta.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--><!--<xi:include href="eXoJCR/jcr/jca.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--><!--<xi:include href="eXoJCR/jcr/other/acl.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--><!--<xi:include href="eXoJCR/jcr/other/acl-ext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/other/link-producer.xml"/> -<!--<xi:include href="eXoJCR/jcr/other/binary-values-processing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />--> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/other/jcr-resources.xml"/> -<!-- data container configs --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/data-container.xml"/> -<!-- <xi:include href="eXoJCR/jcr/data-container-howto.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/db-cleaner-service.xml"/> <!-- tuning guide DOC NOTE: Could possibly be moved to a specific Tuning Guide later --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr/performance-tuning-guide.xml"/> -<!-- JCR Core - DOC NOTE: This section seems to include items covered elsewhere in this guide, or things that are not relevant to EPP - <xi:include href="eXoJCR/core.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --><!-- Web services - DOC NOTE: Red Hat JBoss has two possible Web Services packages. No need to document the eXo offering: - <xi:include href="eXoJCR/ws.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr-with-gatein.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eXoJCR/jcr-with-gatein.xml"/> </part>