[gatein-commits] gatein SVN: r8619 - in epp/docs/branches/5.2/Reference_Guide: en-US and 3 other directories.

Author: jaredmorgs Date: 2012-03-20 00:35:30 -0400 (Tue, 20 Mar 2012) New Revision: 8619 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/5.2/Reference_Guide/en-US/extras/Authentication_Identity_SSO/default109.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml epp/docs/branches/5.2/Reference_Guide/publican.cfg Log: https://bugzilla.redhat.com/show_bug.cgi?id=794455 and https://bugzilla.redhat.com/show_bug.cgi?id=794466 Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Book_Info.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,33 +1,31 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE bookinfo 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; ]> <bookinfo id="book-Reference_Guide-Reference_Guide"> - <title>Reference Guide</title> - <subtitle>An in-depth guide to Enterprise Portal Platform 5.2.0</subtitle> - <productname>JBoss Enterprise Portal Platform</productname> - <productnumber>5.2</productnumber> - <edition>5.2.1</edition> - <pubsnumber>5</pubsnumber> - <abstract> - <para> + <title>Reference Guide</title> + <subtitle>An in-depth guide to Enterprise Portal Platform 5.2.0</subtitle> + <productname>JBoss Enterprise Portal Platform</productname> + <productnumber>5.2</productnumber> + <edition>5.2.1</edition> + <pubsnumber>6</pubsnumber> + <abstract> + <para> This Reference Guide is a high-level usage document. It deals with more advanced topics than the Installation and User Guides, adding new content or taking concepts discussed in the earlier documents further. It aims to provide supporting documentation for advanced users of the JBoss Enterprise Portal Platform product. Its primary focus is on advanced use of the product and it assumes an intermediate or advanced knowledge of the technology and terms. </para> - - </abstract> - <corpauthor> - <inlinemediaobject> - <imageobject> - <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" /> - </imageobject> - - </inlinemediaobject> - - </corpauthor> - <!-- FOR PUBLICAN --> <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude"> <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="fallback_content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </abstract> + <corpauthor> + <inlinemediaobject> + <imageobject> + <imagedata fileref="Common_Content/images/title_logo.svg" format="SVG"/> + </imageobject> + </inlinemediaobject> + </corpauthor> +<!-- FOR PUBLICAN --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Common_Content/Legal_Notice.xml"> + <!-- FOR JDOCBOOK: --> <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="fallback_content/Legal_Notice.xml"/> </xi:fallback> - </xi:include> - <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </xi:include> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Author_Group.xml"/> </bookinfo> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Reference_Guide.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,26 +1,17 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<?xml version='1.0' encoding='UTF-8'?> +<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book 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; ]> - <book> - <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/PortalDevelopment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/PortletDevelopment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -<!-- <xi:include href="modules/GadgetDevelopment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> - <xi:include href="modules/AuthenticationAndIdentity.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/WSRP.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/Advanced.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="modules/eXoJCR.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - </book> +<book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Preface.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/PortalDevelopment.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/PortletDevelopment.xml"/> +<!-- <xi:include href="modules/GadgetDevelopment.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/AuthenticationAndIdentity.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/WSRP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/Advanced.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/eXoJCR.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Revision_History.xml"/> +</book> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/Revision_History.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,284 +1,268 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE appendix 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; ]> <appendix id="appe-Reference_Guide-Revision_History"> - <title>Revision History</title> - <simpara> - <revhistory> - <revision> - <revnumber>5.2.1-5</revnumber> - <date>Mon Jan 09 2012</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Added new content to Authentication and Identity.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-100</revnumber> - <date>Wed Dec 14 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Publication build.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-19</revnumber> - <date>Fri Dec 9 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Further QE-related edits.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-17</revnumber> - <date>Thu Dec 8 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Re-import GateIn WSRP content.</member> - <member>Incorporate QE feedback (JBEPP-1431).</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-14</revnumber> - <date>Wed Dec 7 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>JBEPP-1431: Incorporate QA feedback.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-13</revnumber> - <date>Thu Dec 1 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Ported GateIn WSRP update (r8166).</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-12</revnumber> - <date>Wed Nov 30 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Added "Define Custom CSS File" section.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-11</revnumber> - <date>Tue Nov 29 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Corrected SSO section after porting deprecated GateIn content.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-10</revnumber> - <date>Fri Nov 25 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Ported latest community WSRP content.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-8</revnumber> - <date>Thu Nov 24 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - </author> - <revdescription> - <simplelist> - <member>Finalized first edit pass of eXoJCR content.</member> - <member>Moved eXoJCR section to Part IV.</member> - <member>Clean element ids and fix broken linkends.</member> - </simplelist> - </revdescription> - </revision> - <revision> - <revnumber>5.2.0-6</revnumber> - <date>Thu Nov 17 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Incorporated GateIn SSO updates.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-5</revnumber> - <date>Tue Nov 15 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Staging for beta release.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-4</revnumber> - <date>Wed Nov 9 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Republished for review/feedback.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-3</revnumber> - <date>Wed Nov 2 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Staged for review of updated Foundations and eXo JCR content.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-2</revnumber> - <date>Tue Sep 27 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Incorporated eXo JCR 1.14 documentation.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-5</revnumber> - <date>Wed Sep 14 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Added Global Portlet Data section.</member> - - </simplelist> - - </revdescription> - - </revision> - <revision> - <revnumber>5.2.0-1</revnumber> - <date>Mon Aug 29 2011</date> - <author> - <firstname>Scott</firstname> - <surname>Mumford</surname> - <email></email> - - </author> - <revdescription> - <simplelist> - <member>Updating version and resetting pubs/ed numbers.</member> - - </simplelist> - - </revdescription> - - </revision> - - </revhistory> - - </simpara> + <title>Revision History</title> + <simpara> + <revhistory> + <revision> + <revnumber>5.2.1-6</revnumber> + <date>Tue Mar 20 2112</date> + <author> + <firstname>Jared</firstname> + <surname>Morgan</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>https://bugzilla.redhat.com/show_bug.cgi?id=794466 - Added line break to Redirect to CAS procedure code sample.</member> + <member>https://bugzilla.redhat.com/show_bug.cgi?id=794455 - Changed the LocalePolicy file path as declared in the diff.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.1-5</revnumber> + <date>Mon Jan 09 2012</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Added new content to Authentication and Identity.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-100</revnumber> + <date>Wed Dec 14 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Publication build.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-19</revnumber> + <date>Fri Dec 9 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Further QE-related edits.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-17</revnumber> + <date>Thu Dec 8 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Re-import GateIn WSRP content.</member> + <member>Incorporate QE feedback (JBEPP-1431).</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-14</revnumber> + <date>Wed Dec 7 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>JBEPP-1431: Incorporate QA feedback.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-13</revnumber> + <date>Thu Dec 1 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Ported GateIn WSRP update (r8166).</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-12</revnumber> + <date>Wed Nov 30 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Added &quot;Define Custom CSS File&quot; section.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-11</revnumber> + <date>Tue Nov 29 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Corrected SSO section after porting deprecated GateIn content.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-10</revnumber> + <date>Fri Nov 25 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Ported latest community WSRP content.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-8</revnumber> + <date>Thu Nov 24 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Finalized first edit pass of eXoJCR content.</member> + <member>Moved eXoJCR section to Part IV.</member> + <member>Clean element ids and fix broken linkends.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-6</revnumber> + <date>Thu Nov 17 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Incorporated GateIn SSO updates.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-5</revnumber> + <date>Tue Nov 15 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Staging for beta release.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-4</revnumber> + <date>Wed Nov 9 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Republished for review/feedback.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-3</revnumber> + <date>Wed Nov 2 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Staged for review of updated Foundations and eXo JCR content.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-2</revnumber> + <date>Tue Sep 27 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Incorporated eXo JCR 1.14 documentation.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-5</revnumber> + <date>Wed Sep 14 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Added Global Portlet Data section.</member> + </simplelist> + </revdescription> + </revision> + <revision> + <revnumber>5.2.0-1</revnumber> + <date>Mon Aug 29 2011</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email/> + </author> + <revdescription> + <simplelist> + <member>Updating version and resetting pubs/ed numbers.</member> + </simplelist> + </revdescription> + </revision> + </revhistory> + </simpara> </appendix> - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/extras/Authentication_Identity_SSO/default109.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/extras/Authentication_Identity_SSO/default109.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/extras/Authentication_Identity_SSO/default109.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -5,8 +5,7 @@ <!-- This should point to your SSO authentication server --> <param-name>LOGIN_URL</param-name> <!-- If casRenewTicket param value of InitiateLoginServlet is: not specified or false --> - <param-value>http://localhost:8888/cas/login?service= - http://localhost:8080/portal/initiatessologin</param-value> + <param-value>http://localhost:8888/cas/login?service=http://localhost:8080/portal/initiatessologin</param-value> <!-- If casRenewTicket param value of InitiateLoginServlet is : true --> <!-- <param-value>http://localhost:8888/cas/login? service=http://localhost:8080/portal/initiatessologin&amp;renew=true</param-value> @@ -55,4 +54,4 @@ <filter-mapping> <filter-name>InitiateLoginFilter</filter-name> <url-pattern>/initiatessologin</url-pattern> - </filter-mapping> \ No newline at end of file + </filter-mapping> Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,79 +1,70 @@ -<?xml version='1.0' encoding='utf-8' ?> +<?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE section 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; ]> <section id="sect-Reference_Guide-SSO_Single_Sign_On"> - <title>SSO - Single Sign On</title> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Overview"> - <title>Overview</title> - <para> + <title>SSO - Single Sign On</title> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Overview"> + <title>Overview</title> + <para> JBoss Enterprise Portal Platform provides an implementation of Single Sign On (<literal>SSO</literal>) as an integration and aggregation platform. </para> - <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. </para> - <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. </para> - <para> + <para> This section will cover the implementation of four different SSO plug-ins with JBoss Enterprise Portal Platform: </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service" /> + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"/> </para> - - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism" /> + </listitem> + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/> </para> - - </listitem> - - </itemizedlist> - <note> - <title>Prerequisites</title> - <para> - In this tutorial, the SSO server is being installed in a Tomcat environment. Tomcat can be obtained from <ulink type="http" url="http://tomcat.apache.org"> http://tomcat.apache.org </ulink> . + </listitem> + </itemizedlist> + <note> + <title>Prerequisites</title> + <para> + In this tutorial, the SSO server is being installed in a Tomcat environment. Tomcat can be obtained from <ulink url="http://tomcat.apache.org" type="http"> http://tomcat.apache.org </ulink> . </para> - - </note> - <para> + </note> + <para> All the packages required for SSO setup can be found in a zip file located in the <filename>jboss-epp-<replaceable>VERSION</replaceable>/gatein-sso</filename> directory of the JBoss Enterprise Portal Platform binary package. </para> - <para> + <para> In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. </para> - <warning> - <para> + <warning> + <para> Users are advised to not run any portal extensions that could override the data when manipulating the <filename>gatein.ear</filename> file directly. </para> - <!-- Removed in GateIn reference-guide +<!-- Removed in GateIn reference-guide <para> 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> - <!-- Source Metadata + </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> +<!-- Source Metadata URL: https://issues.jboss.org/browse/JBQA-4530 Author [w/email]: Marek Posolda (mposolda(a)redhat.com) @@ -82,477 +73,397 @@ URL: https://issues.jboss.org/browse/JBEPP-615 Author [w/email]: Marek Posolda (mposolda(a)redhat.com) - --> <para> + --> <para> The JBoss SSO valve is useful to authenticate a user on one JBoss Enterprise Portal Platform node in a cluster and have that authentication automatically carry across to other nodes in the cluster. </para> - <para> + <para> This authentication can also be used in any other web applications which may require authentication, <emphasis role="bold">provided that these applications use same roles as the main portal instance</emphasis>. Attempting to use an SSO authentication in an application that uses different roles may create authorization errors (<emphasis role="bold">403</emphasis> errors, for example). </para> - <note> - <title>Reauthentication</title> - <para> + <note> + <title>Reauthentication</title> + <para> This behavior is coming from the fact that same JAAS principal is added by SSO valve to all HTTP requests, even to other web applications. </para> - <para> + <para> So the same roles are required because of it. There is an alternative that allows you to configure the SSO valve with the <parameter>requireReauthentication=true</parameter> parameter, which will force the SSO valve to perform reauthentication with saved credentials in each HTTP request against security domain of particular web application where the request is coming. </para> - <para> + <para> This will ensure that a new principal for that web application will be created with updated roles for that web application. </para> - <para> + <para> In other words; when <parameter>requireReauthentication</parameter> is <emphasis role="bold">false</emphasis> (the default state), you need to have the same roles among web applications. When <parameter>requireReauthentication</parameter> is <emphasis role="bold">true</emphasis> you need to have same username and passwords. </para> - - </note> - <para> - More info about the JBoss SSO valve can be found at <ulink type="http" url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform... />. + </note> + <para> + More info about the JBoss SSO valve can be found at <ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Platform... type="http"/>. </para> - <para> + <para> To successfully implement SSO integration, do the following: </para> - <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-SSO_Integration"> - <title>SSO Integration</title> - <step> - <para> + <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-SSO_Integration"> + <title>SSO Integration</title> + <step> + <para> Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jbossweb.sar/server.xml</filename> file and uncomment one of the two <parameter>Valve</parameter> entries: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> For a <emphasis>non-clustered</emphasis> implementation, uncomment: </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.apache.catalina.authenticator.SingleSignOn" /&gt; + <programlisting language="XML" role="XML">&lt;Valve className=&quot;org.apache.catalina.authenticator.SingleSignOn&quot; /&gt; </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> For a <emphasis>clustered</emphasis> implementation, uncomment: </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt;</programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + <programlisting language="XML" role="XML">&lt;Valve className=&quot;org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn&quot; /&gt;</programlisting> + </listitem> + </itemizedlist> + </step> + <step> + <para> For implementation of the SSO valve among the different nodes of cluster, all the nodes must share the same domain (<emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>, for example). </para> - <para> + <para> This domain needs to be configured in the SSO valve parameter <parameter>cookieDomain</parameter>. This is required because the SSO valve adds the cookie <emphasis role="bold">JSESSIONIDSSO</emphasis>, which is, by default bound only to the host where the request is originating. </para> - <para> + <para> When the <parameter>cookieDomain</parameter> parameter is used, the cookie is bound to the domain (like <emphasis>yourdomain.com</emphasis>), which will ensure that it is shared among both hosts <emphasis>node1.yourdomain.com</emphasis> and <emphasis>node2.yourdomain.com</emphasis>. </para> - <para> + <para> So in this case, the valve configuration would be: </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" -cookieDomain="yourdomain.com" /&gt; + <programlisting language="XML" role="XML">&lt;Valve className=&quot;org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn&quot; +cookieDomain=&quot;yourdomain.com&quot; /&gt; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Another important thing is that both cluster nodes needs to be on same cluster (using same parameter <emphasis role="bold">-g</emphasis> and same parameter <emphasis role="bold">-u</emphasis> and also using parameter <emphasis role="bold">-Dexo.profiles=cluster</emphasis>). </para> - <para> + <para> They must also share the same NFS directory and the same database and apply all the configuration needed for JBoss Enterprise Portal Platform cluster. </para> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_in_a_physical_cluster"> - <title>Testing SSO in a physical cluster</title> - <para> + </step> + </procedure> + <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_in_a_physical_cluster"> + <title>Testing SSO in a physical cluster</title> + <para> In this example, we will try to simulate testing on more physical machines by simply using virtual hosts on single machine. </para> - - </formalpara> - <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> - <title>Testing the SSO Valve</title> - <step> - <para> + </formalpara> + <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> + <title>Testing the SSO Valve</title> + <step> + <para> If you are using a Linux system, you can configure file <emphasis role="bold">/etc/hosts</emphasis> to contain these lines: </para> - -<programlisting> + <programlisting> 127.0.1.1 machine1.yourdomain.com 127.0.1.2 machine2.yourdomain.com </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/all/<replaceable>&lt;PROFILE&gt;</replaceable>/jbossweb.sar/server.xml</filename> file. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Uncomment the line: </para> - -<programlisting language="XML" role="XML">&lt;!-- -&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" /&gt; + <programlisting language="XML" role="XML">&lt;!-- +&lt;Valve className=&quot;org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn&quot; /&gt; --&gt; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> And edit it to match the following: </para> - -<programlisting language="XML" role="XML">&lt;Valve className="org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn" -cookieDomain="yourdomain.com" /&gt; + <programlisting language="XML" role="XML">&lt;Valve className=&quot;org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn&quot; +cookieDomain=&quot;yourdomain.com&quot; /&gt; </programlisting> - <para> + <para> This will ensure the <literal>JSESSIONIDSSO</literal> cookie is used in the correct domain, allowing the SSO authentication to occur. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Copy server configuration <emphasis role="bold">all</emphasis> and create another two configurations <emphasis role="bold">node1</emphasis> and <emphasis role="bold">node2</emphasis> from it. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Start both cluster nodes with commands: </para> - -<programlisting> + <programlisting> ./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; ./run.sh -c node2 -b machine2.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=1 &amp; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Go to <uri>http://machine1.yourdomain.com:8080/portal</uri> and login as a user. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Access a private URL on the second host, such as <uri>http://machine2.yourdomain.com:8080/portal/dologin</uri>, for example. </para> - <para> + <para> Now you should be logged directly into <literal>machine2</literal> thanks to SSO valve. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Logout from SSO initiating machine1.yourdomain.com should also logged you out from other cluster nodes. So you should be logout directly from machine2 as well. </para> - - </step> - - </procedure> - - <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> + </step> + </procedure> + <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> As mentioned earlier, in order to use SSO authentication between JBoss Enterprise Portal Platform instances and other web applications, the roles defined in the web application must match those used in the portal instance (unless you have the <parameter>requireReauthentication</parameter> parameter set to <literal>true</literal>). </para> - - </formalpara> - <para> + </formalpara> + <para> As an example, to use the SSO Valve to authenticate a user in both a portal instance and the JMX Console, the following actions would be required: </para> - <procedure> - <title></title> - <step> - <para> + <procedure> + <title/> + <step> + <para> Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/node1/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and edit it as follows: </para> - <substeps> - <step> - <para> + <substeps> + <step> + <para> Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;auth-constraint&gt;</parameter> element (line <literal>110</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal>: </para> - -<programlisting language="XML" role="XML">&lt;auth-constraint&gt; + <programlisting language="XML" role="XML">&lt;auth-constraint&gt; &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; &lt;role-name&gt;users&lt;/role-name&gt; &lt;/auth-constraint&gt;</programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Change the <parameter>&lt;role-name&gt;</parameter> entry in the <parameter>&lt;security-role&gt;</parameter> element (line <literal>120</literal>) from <literal>JBossAdmin</literal> to <literal>users</literal> </para> - -<programlisting language="XML" role="XML">&lt;security-role&gt; + <programlisting language="XML" role="XML">&lt;security-role&gt; &lt;!--&lt;role-name&gt;JBossAdmin&lt;/role-name&gt;--&gt; &lt;role-name&gt;users&lt;/role-name&gt; &lt;/security-role&gt;</programlisting> - - </step> - - </substeps> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_With_Other_Web_Applications"> - <title>Testing SSO With Other Web Applications</title> - <para> + </step> + </substeps> + </step> + </procedure> + <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_SSO_With_Other_Web_Applications"> + <title>Testing SSO With Other Web Applications</title> + <para> To test that SSO authentication is enabled from portal instances to other web applications (in this case, the JMX Console), do the following: </para> - - </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> - <step> - <para> + </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> + <step> + <para> Start a portal instance on one node: </para> - -<programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; + <programlisting>./run.sh -c node1 -b machine1.yourdomain.com -Dexo.profiles=cluster -Djboss.messaging.ServerPeerID=0 &amp; </programlisting> - - </step> - <step> - <para> - Navigate to <uri>http://machine1.yourdomain.com:8080/portal/private/classic</uri> and authenticate with the pre-configured user account "<systemitem>root</systemitem>" (password "<systemitem>gtn </systemitem>"). + </step> + <step> + <para> + Navigate to <uri>http://machine1.yourdomain.com:8080/portal/private/classic</uri> and authenticate with the pre-configured user account &quot;<systemitem>root</systemitem>&quot; (password &quot;<systemitem>gtn </systemitem>&quot;). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Navigate to <uri>http://machine1.yourdomain.com:8080/jmx-console</uri>. You should be automatically authenticated into the JMX Console. </para> - - </step> - - </procedure> - - <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Using_SSO_to_Authenticate_From_the_Public_Page"> - <title>Using SSO to Authenticate From the Public Page</title> - <para> - The previous configuration changes in this section are useful if a user is using a secured URL (<ulink type="http" url="http://localhost:8080/portal/private/classic" />, for example) to log in to the portal instance. + </step> + </procedure> + <formalpara id="form-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Using_SSO_to_Authenticate_From_the_Public_Page"> + <title>Using SSO to Authenticate From the Public Page</title> + <para> + The previous configuration changes in this section are useful if a user is using a secured URL (<ulink url="http://localhost:8080/portal/private/classic" type="http"/>, for example) to log in to the portal instance. </para> - - </formalpara> - <para> - Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal (<ulink type="http" url="http://localhost:8080/portal/classic" />). + </formalpara> + <para> + Further changes are needed however, if SSO authentication is required to work with the <guilabel>Sign In</guilabel> button on the front page of the portal (<ulink url="http://localhost:8080/portal/classic" type="http"/>). </para> - <para> + <para> To enable this functionality, the <guilabel>Sign In</guilabel> link must redirect to some secured URL, which will ensure that JAAS authentication will be enforced directly without showing login dialog. </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> - <step> - <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> + <step> + <para> Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file and edit the line: </para> - -<programlisting language="Java" role="java">&lt;a class="Login" onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; + <programlisting language="Java" role="java">&lt;a class=&quot;Login&quot; onclick=&quot;$signInAction&quot;&gt;&lt;%=_ctx.appRes(&quot;UILoginForm.label.Signin&quot;)%&gt;&lt;/a&gt; </programlisting> - <para> + <para> To read: </para> - -<programlisting language="Java" role="java">&lt;a class="Login" href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILoginForm.label.Signin")%&gt;&lt;/a&gt; + <programlisting language="Java" role="java">&lt;a class=&quot;Login&quot; href=&quot;/portal/private/classic&quot;&gt;&lt;%=_ctx.appRes(&quot;UILoginForm.label.Signin&quot;)%&gt;&lt;/a&gt; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Open the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file and change the line: </para> - -<programlisting language="Java" role="java">&lt;a onclick="$signInAction"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; + <programlisting language="Java" role="java">&lt;a onclick=&quot;$signInAction&quot;&gt;&lt;%=_ctx.appRes(&quot;UILogoPortlet.action.signin&quot;)%&gt;&lt;/a&gt; </programlisting> - <para> + <para> To read: </para> - -<programlisting language="Java" role="java">&lt;a href="/portal/private/classic"&gt;&lt;%=_ctx.appRes("UILogoPortlet.action.signin")%&gt;&lt;/a&gt; + <programlisting language="Java" role="java">&lt;a href=&quot;/portal/private/classic&quot;&gt;&lt;%=_ctx.appRes(&quot;UILogoPortlet.action.signin&quot;)%&gt;&lt;/a&gt; </programlisting> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"> - <title>Central Authentication Service</title> - <para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Central_Authentication_Service"> + <title><remark>BZ#794466 </remark>Central Authentication Service</title> + <para> This Single Sign On plugin enables seamless integration between JBoss Enterprise 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> + <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> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-CAS_server"> - <title>CAS server</title> - <step> - <para> + <procedure id="proc-Reference_Guide-Central_Authentication_Service-CAS_server"> + <title>CAS server</title> + <step> + <para> Set up the server to authenticate against the portal login module. </para> - - </step> - <step> - <para> - Downloaded CAS from <ulink type="http" url="http://www.jasig.org/cas/download"> http://www.jasig.org/cas/download </ulink> . + </step> + <step> + <para> + Downloaded CAS from <ulink url="http://www.jasig.org/cas/download" type="http"> http://www.jasig.org/cas/download </ulink> . </para> - <para> + <para> The version, tested with these instructions is <emphasis role="bold">CAS 3.3.5</emphasis>. Other versions may work. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Extract the downloaded file into a suitable location. This location will be referred to as <replaceable>CAS_DIR</replaceable> in the following example. </para> - - </step> - - </procedure> - - <para> + </step> + </procedure> + <para> The simplest way to configure the web archive is to make the necessary changes directly into the CAS codebase. </para> - <note> - <para> - To perform the final build step and complete these instructions you will need the Apache Maven 2. Download it from <ulink type="http" url="http://maven.apache.org/download.html"> here </ulink> . + <note> + <para> + 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> . </para> - - </note> - <para> + </note> + <para> Change the default authentication handler with the one provided by JBoss Enterprise Portal Platform. </para> - <para> + <para> The CAS Server Plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. </para> - <para> + <para> In order for the plugin 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> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-Modifying_CAS_server"> - <title>Modifying CAS server</title> - <step> - <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>/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</filename> </para> - - </step> - <step> - <para> + </step> + <step> + <para> Replace this code: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default102.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <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). Also available in <filename>PORTAL_SSO/cas/plugin/WEB-INF/deployerConfigContext.xml</filename>.): </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default103.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <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 <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/sso-cas-plugin-&lt;VERSION&gt;.jar</filename> and <filename><replaceable>PORTAL_SSO</replaceable>/cas/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> into the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/src/main/webapp/WEB-INF/lib</filename> created directory. </para> - - </step> - <step> - <para> + </step> + <step> + <para> If you have not already done so, download an instance of Tomcat and extract it into a suitable location (which will be called <filename>TOMCAT_HOME</filename> for these instructions). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform. </para> - <note> - <para> + <note> + <para> If JBoss Enterprise Portal Platform is running on the same machine as Tomcat other ports will need to be changed in addition to 8080 in order to avoid conflicts. They can be changed to any free port. For example; you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. </para> - - </note> - - </step> - <step> - <para> + </note> + </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>mvn install </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> Copy the <filename><replaceable>CAS_DIR</replaceable>/cas-server-webapp/target/cas.war</filename> file into the <filename>TOMCAT_HOME/webapps</filename> directory. </para> - <para> - Tomcat should start without issue and should be accessible at <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . + <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> + <note> + <para> At this stage the login functionality will not be available. </para> - - </note> - <mediaobject> - <imageobject> - <imagedata fileref="images/AuthenticationAndIdentity/SSO/cas.png" format="PNG" scale="100" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <note> - <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 : </para> - -<programlisting> -&lt;bean id="logoutController" class="org.jasig.cas.web.LogoutController" - p:centralAuthenticationService-ref="centralAuthenticationService" - p:logoutView="casLogoutView" - p:warnCookieGenerator-ref="warnCookieGenerator" - p:ticketGrantingTicketCookieGenerator-ref="ticketGrantingTicketCookieGenerator" - p:followServiceRedirects="true"/&gt; + <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> - <procedure id="proc-Reference_Guide-Central_Authentication_Service-Setup_the_CAS_client"> - <title>Setup the CAS client</title> - <step> - <para> + </note> + <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>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename>) directory. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default105.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - There's a line comment already in this source file to assist you. + <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> + <para> + There&apos;s a line comment already in this source file to assist you. </para> - <!-- Removing as per https://issues.jboss.org/browse/JBEPP-1350 +<!-- 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> @@ -561,554 +472,455 @@ portalContainerName=portal realmName=gatein-domain; </programlisting> - --> - </step> - <step> - <para> + --> </step> + <step> + <para> The installation can be tested at this point (assuming the CAS server on Tomcat is running): </para> - <procedure> - <step> - <para> - Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to <ulink type="http" url="http://localhost:8888/cas"> http://localhost:8888/cas </ulink> . + <procedure> + <step> + <para> + Start (or restart) JBoss Enterprise Portal Platform and direct your web browser to <ulink url="http://localhost:8888/cas" type="http"> http://localhost:8888/cas </ulink> . </para> - - </step> - <step> - <para> + </step> + <step> + <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> - + </step> </procedure> - - <para> + </step> + </procedure> + <para> To utilize the Central Authentication Service, JBoss Enterprise Portal Platform needs to redirect all user authentication to the CAS server. </para> - <para> + <para> Information about where the CAS is hosted must be properly configured within the JBoss Enterprise Portal Platform 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 '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + <procedure id="proc-Reference_Guide-Central_Authentication_Service-Redirect_to_CAS"> + <title><remark>BZ#794466 </remark>Redirect to CAS</title> + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default106.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + <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>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default107.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <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: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default108.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <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>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default109.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> + <remark>BZ#794466 - Updated formatting of line break. in URL</remark> + <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 your portal. </para> - - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> - <title>Java Open Single Sign-On Project</title> - <para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> + <title>Java Open Single Sign-On Project</title> + <para> This Single Sign On plugin enables seamless integration between JBoss Enterprise Portal Platform and the Java Open Single Sign-On Project (<emphasis role="bold">JOSSO</emphasis>) Single Sign On Framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"> www.josso.org </ulink> . </para> - <para> + <para> This section details setting up the JOSSO server to authenticate against the JBoss Enterprise Portal Platform login module. </para> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"> - <title>JOSSO server</title> - <step> - <para> - Download JOSSO from <ulink type="http" url="http://sourceforge.net/projects/josso/files/"> http://sourceforge.net/projects/josso/files/ </ulink> . + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"> + <title>JOSSO server</title> + <step> + <para> + Download JOSSO from <ulink url="http://sourceforge.net/projects/josso/files/" type="http"> http://sourceforge.net/projects/josso/files/ </ulink> . </para> - <note> - <para> + <note> + <para> Use the package that embeds Apache Tomcat. The integration was tested with JOSSO-1.8.1. </para> - - </note> - - </step> - <step> - <para> + </note> + </step> + <step> + <para> Extract the package into what will be called <filename>JOSSO_HOME</filename> in this example. </para> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> - <title>Modifying JOSSO server</title> - <step> - <para> + </step> + </procedure> + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> + <title>Modifying JOSSO server</title> + <step> + <para> Copy the files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/plugin</filename> into the <filename>JOSSO_HOME</filename> directory created in the last step. </para> - <para> + <para> This action should replace or add the following files to the <filename>JOSSO_HOME/webapps/josso/WEB-INF/lib</filename> directory: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <filename>JOSSO_HOME/lib/josso-gateway-config.xml</filename> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <filename>JOSSO_HOME/lib/josso-gateway-gatein-stores.xml</filename> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/gatein.properties</filename> </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Edit <filename>TOMCAT_HOME/conf/server.xml</filename> file and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. <note> - <title>Port Conflicts</title> - <para> + <title>Port Conflicts</title> + <para> If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change admin port from 8005 to 8805, and AJP port from 8009 to 8809. </para> + </note> - </note> - </para> - - </step> - <step> - <para> - Tomcat will start and allow access to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> but at this stage login will not be available. + </step> + <step> + <para> + Tomcat will start and allow access to <ulink url="http://localhost:8888/josso/signon/login.do" type="http"> http://localhost:8888/josso/signon/login.do </ulink> but at this stage login will not be available. </para> - <mediaobject> - <imageobject> - <imagedata fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> - <title>Setup the JOSSO client</title> - <step> - <para> + <mediaobject> + <imageobject> + <imagedata width="444" fileref="images/AuthenticationAndIdentity/SSO/opensso.png" format="PNG"/> + </imageobject> + </mediaobject> + </step> + </procedure> + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> + <title>Setup the JOSSO client</title> + <step> + <para> Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/lib</filename> into <filename>gatein.ear/lib</filename> (or into <filename>GATEIN_HOME/lib</filename> if the product is running in Tomcat). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Copy the <filename><replaceable>PORTAL_SSO</replaceable>/josso/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> file into the <filename>gatein.ear/02portal.war/WEB-INF/classes</filename> directory (or into <filename>JBOSS_HOME/webapps/portal.war/WEB-INF/classes</filename>, or <filename>GATEIN_HOME/conf</filename> if the product is running in Tomcat). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text"/></programlisting> + </step> + <step> + <para> In Tomcat, edit <filename>JBOSS_HOME/conf/jaas.conf</filename> and uncomment this section: </para> - -<programlisting>org.gatein.sso.agent.login.SSOLoginModule required; + <programlisting>org.gatein.sso.agent.login.SSOLoginModule required; org.exoplatform.services.security.j2ee.TomcatLoginModule requiredtm portalContainerName=portal realmName=gatein-domain; </programlisting> - - </step> - <step> - <para> + </step> + <step> + <para> The installation can be tested at this point. </para> - <substeps> - <step> - <para> - Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink type="http" url="http://localhost:8888/josso/signon/login.do"> http://localhost:8888/josso/signon/login.do </ulink> . + <substeps> + <step> + <para> + Start (or restart) JBoss Enterprise Portal Platform, and (assuming the JOSSO server on Tomcat is running) direct your browser to <ulink url="http://localhost:8888/josso/signon/login.do" type="http"> http://localhost:8888/josso/signon/login.do </ulink> . </para> - - </step> - <step> - <para> + </step> + <step> + <para> Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. </para> - - </step> - - </substeps> - - </step> - - </procedure> - - <para> + </step> + </substeps> + </step> + </procedure> + <para> The next part of the process is to redirect all user authentication to the JOSSO server. </para> - <para> + <para> Information about where the JOSSO server is hosted must be properly configured within the JBoss Enterprise Portal Platform instance. The required configuration is done by modifying four files: </para> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> - <title>Setup the portal to redirect to JOSSO</title> - <step> - <para> - In the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the 'Sign In' link as follows: + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> + <title>Setup the portal to redirect to JOSSO</title> + <step> + <para> + In the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the &apos;Sign In&apos; link as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text"/></programlisting> + </step> + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text"/></programlisting> + </step> + <step> + <para> Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text"/></programlisting> + </step> + <step> + <para> Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text"/></programlisting> + </step> + </procedure> + <para> From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. </para> - - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"> - <title>OpenSSO</title> - <para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"> + <title>OpenSSO</title> + <para> This section details the setting up of OpenSSO server to authenticate against the JBoss Enterprise Portal Platform login module. </para> - <procedure id="proc-Reference_Guide-OpenSSO-Obtaining_OpenSSO"> - <title>Obtaining OpenSSO</title> - <step> - <para> - OpenSSO must be purchased from <ulink type="http" url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... Oracle </ulink> . + <procedure id="proc-Reference_Guide-OpenSSO-Obtaining_OpenSSO"> + <title>Obtaining OpenSSO</title> + <step> + <para> + OpenSSO must be purchased from <ulink url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... type="http"> Oracle </ulink> . </para> - <para> - For testing purposes, use OpenSSO_80U2, which can be downloaded from <ulink type="http" url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... </ulink> . + <para> + For testing purposes, use OpenSSO_80U2, which can be downloaded from <ulink url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... type="http">Oracle </ulink> . </para> - - </step> - <step> - <para> + </step> + <step> + <para> Extract the package into a suitable location. This location will be referred to as <filename>OPENSSO_HOME</filename> in this example. </para> - - </step> - - </procedure> - - <note> - <para> - It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between Enterprise Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink type="http" url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration"... here </ulink> . + </step> + </procedure> + <note> + <para> + It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between Enterprise Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration" type="http"> here </ulink> . </para> - - </note> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> - <title>Modifying the OpenSSO server</title> - <para> + </note> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> + <title>Modifying the OpenSSO server</title> + <para> To configure the web server as required, it is simpler to directly modify the source files. </para> - <para> + <para> The first step is to add the JBoss Enterprise Portal Platform Authentication Plugin. </para> - <para> + <para> The plugin makes secure callbacks to a RESTful service installed on the remote JBoss Enterprise Portal Platform server to authenticate a user. </para> - <para> + <para> In order for the plugin to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. </para> - <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> - <title>Modifying OpenSSO server</title> - <step> - <para> + <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> + <title>Modifying OpenSSO server</title> + <step> + <para> Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as <filename>TOMCAT_HOME</filename> in this example. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Enterprise Portal Platform port. <note> - <para> + <para> If JBoss Enterprise Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. </para> + </note> - </note> - </para> - - </step> - <step> - <para> + </step> + <step> + <para> Ensure the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file matches the following: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text"/></programlisting> + </step> + <step> + <para> Copy the following files into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-&lt;VERSION&gt;.jar</filename> </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-&lt;VERSION&gt;.jar</filename> </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Copy the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/classes/gatein.properties</filename> file into the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> directory. </para> - - </step> - <step> - <para> - Tomcat should start and be able to access <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . + </step> + <step> + <para> + Tomcat should start and be able to access <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . </para> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" scale="110" width="444" /> - </imageobject> - <imageobject role="fo"> - <imagedata align="center" contentwidth="150mm" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG" width="444" /> - </imageobject> - - </mediaobject> - <note> - <para> + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="110" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> + </imageobject> + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> + </imageobject> + </mediaobject> + <note> + <para> Login will not be available at this point. </para> - - </note> - - </step> - - </procedure> - - <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> - <title>Configure the "gatein" realm</title> - <step> - <para> - Direct your browser to <ulink type="http" url="http://localhost:8888/opensso"> http://localhost:8888/opensso </ulink> + </note> + </step> + </procedure> + <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> + <title>Configure the &quot;gatein&quot; realm</title> + <step> + <para> + Direct your browser to <ulink url="http://localhost:8888/opensso" type="http"> http://localhost:8888/opensso </ulink> </para> - - </step> - <step> - <para> + </step> + <step> + <para> Create a default configuration. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Login as <literal>amadmin</literal>. </para> - <important> - <para> - Go to <menuchoice><guimenu>Configuration</guimenu> <guimenuitem> Authentication </guimenuitem> </menuchoice> and follow the link to <guilabel>Core</guilabel> + <important> + <para> + Go to <menuchoice> + <guimenu>Configuration</guimenu> + <guimenuitem> Authentication </guimenuitem> + </menuchoice> and follow the link to <guilabel>Core</guilabel> </para> - <para> + <para> Add a new value with the class name <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>. </para> - <para> + <para> If this is not done <literal>AuthenticationPlugin</literal> is not available among other OpenSSO authentication modules. </para> - - </important> - - </step> - <step> - <para> + </important> + </step> + <step> + <para> Go to the <guilabel>Access control</guilabel> tab and create new realm called <literal>gatein</literal>. </para> - - </step> - <step> - <substeps> - <step> - <para> + </step> + <step> + <substeps> + <step> + <para> Go to the new <literal>gatein</literal> realm and click on the <guilabel>Authentication</guilabel> tab. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Click on <guilabel>LDAPService</guilabel> (at the bottom in the <guilabel>Authentication chaining</guilabel> section). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. </para> - - </step> - - </substeps> - <para> + </step> + </substeps> + <para> These changes enable authentication of the <literal>gatein</literal> realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Go to <guilabel>Advanced properties</guilabel> and change <literal>UserProfile</literal> from <parameter>Required</parameter> to <parameter>Dynamic</parameter> to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Increase the user privileges to allow REST access with the following procedure: </para> - <substeps> - <step> - <para> - Go to <menuchoice><guimenu>Access control</guimenu> <guimenuitem> Top level realm </guimenuitem> <guimenuitem> Privileges </guimenuitem> <guimenuitem> All authenticated users </guimenuitem> </menuchoice>. + <substeps> + <step> + <para> + Go to <menuchoice> + <guimenu>Access control</guimenu> + <guimenuitem> Top level realm </guimenuitem> + <guimenuitem> Privileges </guimenuitem> + <guimenuitem> All authenticated users </guimenuitem> + </menuchoice>. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Check the last two checkboxes: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Read and write access only for policy properties </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Read and write access to all realm and policy properties </para> - - </listitem> - - </itemizedlist> - - </step> - - </substeps> - + </listitem> + </itemizedlist> </step> - <step> - <para> - Repeat step 7 for the '<literal>gatein</literal>' realm as well. + </substeps> + </step> + <step> + <para> + Repeat step 7 for the &apos;<literal>gatein</literal>&apos; realm as well. </para> - - </step> - - </procedure> - - + </step> + </procedure> </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> - <title>Setup the OpenSSO Client</title> - <procedure id="proc-Reference_Guide-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> - <title>Setup the OpenSSO client</title> - <step> - <para> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> + <title>Setup the OpenSSO Client</title> + <procedure id="proc-Reference_Guide-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> + <title>Setup the OpenSSO client</title> + <step> + <para> Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename>JBOSS_HOME/server/default/deploy/gatein.ear/lib</filename> directory. </para> - <para> + <para> Alternatively, in a Tomcat environment, copy the libraries into the <filename>JBOSS_HOME/lib</filename> directory. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit the <filename>jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <!-- Removed as per https://issues.jboss.org/browse/JBEPP-1350 + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text"/></programlisting> + </step> +<!-- Removed as per https://issues.jboss.org/browse/JBEPP-1350 <step> <para> If you are running the product in Tomcat, edit <replaceable>&lt;JBOSS_HOME&gt;</replaceable>/conf/jaas.conf, uncomment the following section and comment all other sections: @@ -1119,189 +931,154 @@ realmName=gatein-domain; </programlisting> </step> - --> <step> - <para> + --> <step> + <para> Test the installation: </para> - <procedure> - <step> - <para> - Access JBoss Enterprise Portal Platform by going to <ulink type="http" url="http://localhost:8888/opensso/UI/Login?realm=gatein"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). + <procedure> + <step> + <para> + Access JBoss Enterprise Portal Platform by going to <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). </para> - - </step> - <step> - <para> + </step> + <step> + <para> Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. </para> - - </step> - - </procedure> - - </step> - - </procedure> - - + </procedure> + </step> + </procedure> </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <para> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + <para> The next part of the process is to redirect all user authentication to the OpenSSO server. </para> - <para> + <para> Information about where the OpenSSO server is hosted must be properly configured within the Enterprise Portal Platform instance. The required configuration is done by modifying three files: </para> - <procedure id="proc-Reference_Guide-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + <procedure id="proc-Reference_Guide-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Modify the '<emphasis role="bold">Sign In</emphasis>' link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text"/></programlisting> + </step> + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text"/></programlisting> + </step> + <step> + <para> Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text"/></programlisting> + </step> + <step> + <para> Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - - </procedure> - - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text"/></programlisting> + </step> + </procedure> + <para> From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form. </para> - </section> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> - <title>SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism</title> - <para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> + <title>SPNEGO - Simple and Protected GSSAPI Negotiation Mechanism</title> + <para> The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. </para> - <para> + <para> For illustrative purposes; a typical use case would be: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> A user logs into their desktop computer with a login that is governed by an Active Directory domain. </para> - - </step> - <step> - <para> + </step> + <step> + <para> The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Enterprise Portal Platform. </para> - - </step> - <step> - <para> + </step> + <step> + <para> The browser transfers the desktop credentials to the web application. </para> - - </step> - <step> - <para> + </step> + <step> + <para> JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the Kerberos ticket from user. </para> - - </step> - <step> - <para> + </step> + <step> + <para> The user experiences a seamless single sign on (SSO) into the web application. </para> - - </step> - - </procedure> - - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> - <title>SPNEGO Server Configuration</title> - <para> + </step> + </procedure> + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> + <title>SPNEGO Server Configuration</title> + <para> In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against JBoss Enterprise Portal Platform. </para> - <note> - <title>SPNEGO Basics</title> - <para> - The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration" /> to see how to integrate SPNEGO with JBoss Enterprise Portal Platform. + <note> + <title>SPNEGO Basics</title> + <para> + The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"/> to see how to integrate SPNEGO with JBoss Enterprise Portal Platform. </para> - <para> + <para> Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment. </para> - - </note> - <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> - <title>SPNEGO Basics</title> - <step> - <para> - Correct the setup of network on the machine. For example, if you are using the "server.local.network" domain as your machine where Kerberos and JBoss Enterprise Portal Platform are localed, add the line containing the machine's IP address to the <emphasis role="bold">/etc/host </emphasis> file. + </note> + <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> + <title>SPNEGO Basics</title> + <step> + <para> + Correct the setup of network on the machine. For example, if you are using the &quot;server.local.network&quot; domain as your machine where Kerberos and JBoss Enterprise Portal Platform are localed, add the line containing the machine&apos;s IP address to the <emphasis role="bold">/etc/host </emphasis> file. </para> - -<programlisting> + <programlisting> 192.168.1.88 server.local.network </programlisting> - <note> - <para> + <note> + <para> It is not recommended you use loopback addresses. </para> - - </note> - - </step> - <step> - <para> + </note> + </step> + <step> + <para> Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Edit the Kerberos configuration file at <emphasis role="bold">/etc/krb5.config</emphasis>, including: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Uncomment on these lines: </para> - -<programlisting> + <programlisting> default_tgs_enctypes = des3-hmac-sha1 default_tkt_enctypes = des3-hmac-sha1 permitted_enctypes = des3-hmac-sha1 </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Add <emphasis role="bold">local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like: </para> - -<programlisting> + <programlisting> [libdefaults] default_realm = LOCAL.NETWORK @@ -1320,7 +1097,7 @@ # # Thie only time when you might need to uncomment these lines and change # the enctypes is if you have local software that will break on ticket -# caches containing ticket encryption types it doesn't know about (such as +# caches containing ticket encryption types it doesn&apos;t know about (such as # old versions of Sun Java). default_tgs_enctypes = des3-hmac-sha1 @@ -1354,18 +1131,14 @@ krb4_convert = true krb4_get_tickets = false </programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Edit the KDC configuraton file at <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> that looks like. </para> - -<programlisting> + <programlisting> [kdcdefaults] kdc_ports = 750,88 @@ -1387,199 +1160,159 @@ kdc = FILE:/home/gatein/krb5logs/kdc.log admin_server = FILE:/home/gatein/krb5logs/kadmin.log </programlisting> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Next, create a KDC database using the following command. </para> - -<programlisting> + <programlisting> sudo krb5_newrealm </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Start the KDC and Kerberos admin servers using these commands: </para> - -<programlisting> + <programlisting> sudo /etc/init.d/krb5-kdc restart sudo /etc/init.d/krb-admin-server restart </programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Add Principals and create Keys. </para> - <itemizedlist> - <listitem> - <para> - Start an interactive 'kadmin' session and create the necessary Principals. + <itemizedlist> + <listitem> + <para> + Start an interactive &apos;kadmin&apos; session and create the necessary Principals. </para> - -<programlisting> + <programlisting> sudo kadmin.local </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Add the JBoss Enterprise Portal Platform machine and keytab file that need to be authenticated. </para> - -<programlisting> + <programlisting> addprinc -randkey HTTP/server.local.network(a)LOCAL.NETWORK ktadd HTTP/server.local.network(a)LOCAL.NETWORK </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Add the default JBoss Enterprise Portal Platform user accounts and enter the password for each created user that will be authenticated. </para> - -<programlisting> + <programlisting> addprinc john addprinc demo addprinc root </programlisting> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Test your changed setup by using the command. </para> - -<programlisting> + <programlisting> kinit -A demo </programlisting> - <itemizedlist> - <listitem> - <para> - If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network's DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. + <itemizedlist> + <listitem> + <para> + If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network&apos;s DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. </para> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> After successful login to Kerberos, you can see your Kerberos ticket when using this command. </para> - -<programlisting> + <programlisting> klist </programlisting> - - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> If you want to logout and destroy your ticket, use this command. </para> - -<programlisting> + <programlisting> kdestroy </programlisting> - - </listitem> - - </itemizedlist> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> - <title>Clients</title> - <para> + </listitem> + </itemizedlist> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> + <title>Clients</title> + <para> After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by JBoss Enterprise Portal Platform as follows: </para> - <procedure> - <step> - <para> + <procedure> + <step> + <para> Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: </para> - -<programlisting> + <programlisting> network.negotiate-auth.allow-proxies = true network.negotiate-auth.delegation-uris = .local.network network.negotiate-auth.gsslib (no-value) network.negotiate-auth.trusted-uris = .local.network network.negotiate-auth.using-native-gsslib = true </programlisting> - - </step> - - </procedure> - - <note> - <para> + </step> + </procedure> + <note> + <para> Consult documentation of your OS or web browser if using different browser than Firefox. </para> - - </note> - - </section> - - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> - <title>JBoss Enterprise Portal Platform Configuration</title> - <para> + </note> + </section> + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> + <title>JBoss Enterprise Portal Platform Configuration</title> + <para> JBoss Enterprise Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO for the portal. Here are the steps to integrate SPNEGO with JBoss Enterprise Portal Platform. </para> - <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> - <title>Advanced SPNEGO Configuration</title> - <step> - <para> + <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> + <title>Advanced SPNEGO Configuration</title> + <step> + <para> Activate the Host authentication. Add the following host login module to the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename>: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - The '<literal>keyTab</literal>' value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics" /> for more details. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text"/></programlisting> + <para> + The &apos;<literal>keyTab</literal>&apos; value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"/> for more details. </para> - - </step> - <step> - <para> - Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a '<literal>SPNEGO</literal>' authenticators property + </step> + <step> + <para> + Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a &apos;<literal>SPNEGO</literal>&apos; authenticators property </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text"/></programlisting> + </step> + <step> + <para> Add the SSO module binaries by copying <emphasis role="bold">PORTAL_SSO/spnego/gatein.ear/lib/sso-agent.jar</emphasis> to the <emphasis role="bold">JBOSS_HOME/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/</emphasis> directory. </para> - <para> + <para> Copy the <emphasis role="bold">PORTAL_SSO/spnego/gatein.ear/lib/sso-spnego.jar</emphasis> file to the <emphasis role="bold">JBOSS_HOME/server/<replaceable>&lt;PROFILE&gt;</replaceable>/lib</emphasis> directory. </para> - - </step> - <!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA + </step> +<!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA <step> <para> Download library <filename>jboss-negotiation-2.0.4.GA</filename> from location @@ -1587,39 +1320,36 @@ and copy this file to <filename>JBOSS_HOME/server/default/lib</filename> directory as well. </para> </step> - --> <step> - <para> + --> <step> + <para> Modify the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text"/></programlisting> + <para> This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain. </para> - - </step> - <step> - <para> + </step> + <step> + <para> Modify <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <para> - This integrates SPNEGO support into the Portal web archive by switching the authentication mechanism from the default "FORM"-based to "SPNEGO"-based authentication. + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text"/></programlisting> + <para> + This integrates SPNEGO support into the Portal web archive by switching the authentication mechanism from the default &quot;FORM&quot;-based to &quot;SPNEGO&quot;-based authentication. </para> - <para> + <para> You can see that the SPNEGO portion also contains the element <code>form-login-config</code>, which is required if you want to enable a fallback to FORM based authentication function. </para> - <para> + <para> In this case, the portal will attempt to authenticate the user with their Kerberos ticket through SPNEGO. If the user does not have a Kerberos ticket, they will be redirected to FORM authentication and via the login screen. </para> - <para> + <para> This configuration ensures the first authentication attempt is though SPNEGO and, if this attempt is unsuccessful, another attempt is made using the FORM method. This could occur if the user does not have a valid Kerberos ticket or if the web browser in use does not support SPNEGO authentication with the Kerberos server. </para> - <para> + <para> If the fallback to FORM function is not required, the <code>form-login-config</code> configuration can be disabled like so: </para> -<programlisting language="XML" role="XML"><![CDATA[<login-config> + <programlisting language="XML" role="XML"><![CDATA[<login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name> <!-- <form-login-config> @@ -1629,64 +1359,48 @@ --> </login-config> ]]></programlisting> - <para> + <para> In this case the user needs to authenticate through SPNEGO and if that fails, the user will receive an authentication error with HTTP code <literal>401</literal>. The FORM fallback will not be offered. </para> - </step> - <step> - <para> + </step> + <step> + <para> Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain. </para> - -<programlisting language="XML" role="XML"><xi:include href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> - Edit the '<emphasis role="bold">Sign In</emphasis>' link in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: + <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text"/></programlisting> + </step> + <step> + <para> + Edit the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in <filename><replaceable>&lt;JBOSS_HOME&gt;</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default129.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - - </step> - <step> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default129.java" parse="text"/></programlisting> + </step> + <step> + <para> Start the JBoss Enterprise Portal Platform; </para> - -<programlisting language="Java" role="Java"><xi:include href="../../extras/Authentication_Identity_SSO/default130.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting> - <note> - <title>Note</title> - <para> + <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default130.java" parse="text"/></programlisting> + <note> + <title>Note</title> + <para> The <replaceable>PROFILE</replaceable> parameter in the above command should be replaced with the server profile modified with the above configuration. </para> - </note> - - </step> - <step> - <para> + </note> + </step> + <step> + <para> Login to Kerberos: </para> - -<programlisting>kinit -A demo + <programlisting>kinit -A demo </programlisting> - - </step> - - </procedure> - - <para> - Clicking the 'Sign In' link on the JBoss Enterprise Portal Platform should automatically sign the 'demo' user into the portal. + </step> + </procedure> + <para> + Clicking the &apos;Sign In&apos; link on the JBoss Enterprise Portal Platform should automatically sign the &apos;demo&apos; user into the portal. </para> - <para> - If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you don't have active Kerberos ticket. You can login with predefined account and password "demo"/"gtn" . + <para> + If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Enterprise Portal Product because you don&apos;t have active Kerberos ticket. You can login with predefined account and password &quot;demo&quot;/&quot;gtn&quot; . </para> - - </section> - </section> - - + </section> </section> - - Modified: epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml =================================================================== --- epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,222 +1,191 @@ -<?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-Localization_Configuration"> - <title>Localization Configuration</title> - <section id="sect-Reference_Guide-Localization_Configuration-Pluggable_Locale_Policy"> - <title>Pluggable Locale Policy</title> - <para> - Every request processed by every portlet is invoked within a context of the current <literal>Locale</literal>. - </para> - <para> - The current <literal>Locale</literal> can be retrieved by calling the <literal>getLocale()</literal> method of <literal>javax.portlet.PortletRequest</literal> interface. - </para> - <para> - The exact algorithm for determining the current <literal>Locale</literal> is not specified by Portlet Specification. Portlet containers implement this the way they deem most appropriate. - </para> - <para> - In JBoss Enterprise Portal Platform, each portal instance has a default language which can be used to present content for new users. Another option is to use each user’s browser language preference, provided it matches one of the available localizations that JBoss Enterprise Portal Platform supports, and only fallback to the portal's default language if no match is found. - </para> - <para> - Every user, while visiting a portal, has an option to change the language of the user interface by using a Language chooser. The choice can be remembered for the duration of the session, or it can be remembered for a longer period using a browser cookie, or, for registered and logged-in users, it can be saved into the user’s profile. - </para> - <para> - As there is more than one way to determine the <literal>Locale</literal> to be used for displaying a portal page, the mechanism for determining the current <literal>Locale</literal> of the request is pluggable in JBoss Enterprise Portal Platform, and the exact algorithm can be customized. - </para> - <section id="sect-Reference_Guide-Pluggable_Locale_Policy-LocalePolicy_API"> - <title>LocalePolicy API</title> - <para> - Customization is achieved by using LocalePolicy API, which is a simple API consisting of one interface, and one class: - </para> - <itemizedlist> - <listitem> - <para> - <literal>org.exoplatform.services.resources.LocalePolicy</literal> interface - </para> - - </listitem> - <listitem> - <para> - <literal>org.exoplatform.services.resources.LocaleContextInfo</literal> class - </para> - - </listitem> - - </itemizedlist> - <para> - The <literal>LocalePolicy</literal> interface defines a single method that is invoked on the installed <literal>LocalePolicy</literal> service implementation: - </para> - -<programlisting language="Java" role="Java">public interface LocalePolicy + <title>Localization Configuration</title> + <section id="sect-Reference_Guide-Localization_Configuration-Pluggable_Locale_Policy"> + <title>Pluggable Locale Policy</title> + <para> + Every request processed by every portlet is invoked within a context of the current <literal>Locale</literal>. + </para> + <para> + The current <literal>Locale</literal> can be retrieved by calling the <literal>getLocale()</literal> method of <literal>javax.portlet.PortletRequest</literal> interface. + </para> + <para> + The exact algorithm for determining the current <literal>Locale</literal> is not specified by Portlet Specification. Portlet containers implement this the way they deem most appropriate. + </para> + <para> + In JBoss Enterprise Portal Platform, each portal instance has a default language which can be used to present content for new users. Another option is to use each user’s browser language preference, provided it matches one of the available localizations that JBoss Enterprise Portal Platform supports, and only fallback to the portal&apos;s default language if no match is found. + </para> + <para> + Every user, while visiting a portal, has an option to change the language of the user interface by using a Language chooser. The choice can be remembered for the duration of the session, or it can be remembered for a longer period using a browser cookie, or, for registered and logged-in users, it can be saved into the user’s profile. + </para> + <para> + As there is more than one way to determine the <literal>Locale</literal> to be used for displaying a portal page, the mechanism for determining the current <literal>Locale</literal> of the request is pluggable in JBoss Enterprise Portal Platform, and the exact algorithm can be customized. + </para> + <section id="sect-Reference_Guide-Pluggable_Locale_Policy-LocalePolicy_API"> + <title>LocalePolicy API</title> + <para> + Customization is achieved by using LocalePolicy API, which is a simple API consisting of one interface, and one class: + </para> + <itemizedlist> + <listitem> + <para> + <literal>org.exoplatform.services.resources.LocalePolicy</literal> interface + </para> + </listitem> + <listitem> + <para> + <literal>org.exoplatform.services.resources.LocaleContextInfo</literal> class + </para> + </listitem> + </itemizedlist> + <para> + The <literal>LocalePolicy</literal> interface defines a single method that is invoked on the installed <literal>LocalePolicy</literal> service implementation: + </para> + <programlisting language="Java" role="Java">public interface LocalePolicy { public Locale determineLocale(LocaleContextInfo localeContext); } </programlisting> - <para> - The <literal>Locale</literal> returned by determineLocale() method is the <literal>Locale</literal> that will be returned to portlets when they call <literal>javax.portlet.PortletRequest.getLocale()</literal> method. - </para> - <para> - The returned <literal>Locale</literal> has to be one of the locales supported by portal, otherwise it will fall back to the portal default <literal>Locale</literal>. - </para> - <para> - The supported locales are listed in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/locales-config.xml</filename> file as described in <xref linkend="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration" /> . - </para> - <para> - The <literal>determineLocale()</literal> method takes a parameter of type <literal>LocaleContextInfo</literal>, which represents a compilation of preferred locales from different sources; user’s profile, portal default, browser language settings, current session, browser cookie. - </para> - <para> - All these different sources of <literal>Locale</literal> configuration or preference are used as input to <literal>LocalePolicy</literal> implementation that decides which <literal>Locale</literal> should be used. - </para> - - </section> - - <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Default_LocalePolicy"> - <title>Default <literal>LocalePolicy</literal></title> - <para> - By default, <literal>org.exoplatform.portal.application.localization.DefaultLocalePolicyService</literal>, an implementation of <literal>LocalePolicy</literal>, is installed to provide the default behavior. This, however, can easily be extended and overridden. A completely new implementation can also be written from scratch. - </para> - <para> - <literal>DefaultLocalePolicyService</literal> treats logged-in users slightly differently than anonymous users. Logged-in users have a profile that can contain language preference, while anonymous users do not. - </para> - <para> - Here is an algorithm used for anonymous users. - </para> - <procedure id="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_anonymous_users"> - <title>An algorithm for anonymous users</title> - <step> - <para> - Iterate over <literal>LocaleContextInfo</literal> properties in the following order: - </para> - <itemizedlist> - <listitem> - <para> - <literal>cookieLocales</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>sessionLocale</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>browserLocales</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>portalLocale</literal> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Get each property's value. If it's a collection, get the first value. - </para> - - </step> - <step> - <para> - If value is one of the supported locales return it as a result. - </para> - - </step> - <step> - <para> - If the value is not in the supported locales set, try to remove country information and check if a language matching locale is in the list of supported locales. If so, return it as a result. - </para> - - </step> - <step> - <para> - Otherwise, continue with the next property. - </para> - - </step> - - </procedure> - - <para> - If no supported locale is found the return locale eventually defaults to <literal>portalLocale</literal>. - </para> - <para> - The algorithm for logged-in users is virtually the same except that the first <literal>Locale</literal> source checked is user's profile. - </para> - <procedure id="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_logged_in_users"> - <title>An algorithm for logged-in users</title> - <step> - <para> - Iterate over <literal>LocaleContextInfo</literal> properties in the following order: - </para> - <itemizedlist> - <listitem> - <para> - <literal>userProfile</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>cookieLocales</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>sessionLocale</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>browserLocales</literal> - </para> - - </listitem> - <listitem> - <para> - <literal>portalLocale</literal> - </para> - - </listitem> - - </itemizedlist> - - </step> - <step> - <para> - Perform the rest of the steps in <xref linkend="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_anonymous_users" />. - </para> - - </step> - - </procedure> - - - </section> - - <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Custom_LocalePolicy"> - <title>Custom <literal>LocalePolicy</literal></title> - <para> - The easiest way to customize the <literal>LocalePolicy</literal> is to extend <literal>DefaultLocalePolicyService</literal>. A study of the source code is required. JavaDocs provide thorough information on this. - </para> - <para> - Most customizations will involve simply overriding one or more of its protected methods. - </para> - <para> - An example of a customization is an already provided <literal>NoBrowserLocalePolicyService</literal>. By overriding just one method, it skips any use of browser language preference. - </para> - -<programlisting language="Java" role="Java">public class NoBrowserLocalePolicyService extends DefaultLocalePolicyService + <para> + The <literal>Locale</literal> returned by determineLocale() method is the <literal>Locale</literal> that will be returned to portlets when they call <literal>javax.portlet.PortletRequest.getLocale()</literal> method. + </para> + <para> + The returned <literal>Locale</literal> has to be one of the locales supported by portal, otherwise it will fall back to the portal default <literal>Locale</literal>. + </para> + <para> + The supported locales are listed in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/locales-config.xml</filename> file as described in <xref linkend="sect-Reference_Guide-Internationalization_Configuration-Locales_Configuration"/> . + </para> + <para> + The <literal>determineLocale()</literal> method takes a parameter of type <literal>LocaleContextInfo</literal>, which represents a compilation of preferred locales from different sources; user’s profile, portal default, browser language settings, current session, browser cookie. + </para> + <para> + All these different sources of <literal>Locale</literal> configuration or preference are used as input to <literal>LocalePolicy</literal> implementation that decides which <literal>Locale</literal> should be used. + </para> + </section> + <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Default_LocalePolicy"> + <title>Default LocalePolicy</title> + <para> + By default, <literal>org.exoplatform.portal.application.localization.DefaultLocalePolicyService</literal>, an implementation of <literal>LocalePolicy</literal>, is installed to provide the default behavior. This, however, can easily be extended and overridden. A completely new implementation can also be written from scratch. + </para> + <para> + <literal>DefaultLocalePolicyService</literal> treats logged-in users slightly differently than anonymous users. Logged-in users have a profile that can contain language preference, while anonymous users do not. + </para> + <para> + Here is an algorithm used for anonymous users. + </para> + <procedure id="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_anonymous_users"> + <title>An algorithm for anonymous users</title> + <step> + <para> + Iterate over <literal>LocaleContextInfo</literal> properties in the following order: + </para> + <itemizedlist> + <listitem> + <para> + <literal>cookieLocales</literal> + </para> + </listitem> + <listitem> + <para> + <literal>sessionLocale</literal> + </para> + </listitem> + <listitem> + <para> + <literal>browserLocales</literal> + </para> + </listitem> + <listitem> + <para> + <literal>portalLocale</literal> + </para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Get each property&apos;s value. If it&apos;s a collection, get the first value. + </para> + </step> + <step> + <para> + If value is one of the supported locales return it as a result. + </para> + </step> + <step> + <para> + If the value is not in the supported locales set, try to remove country information and check if a language matching locale is in the list of supported locales. If so, return it as a result. + </para> + </step> + <step> + <para> + Otherwise, continue with the next property. + </para> + </step> + </procedure> + <para> + If no supported locale is found the return locale eventually defaults to <literal>portalLocale</literal>. + </para> + <para> + The algorithm for logged-in users is virtually the same except that the first <literal>Locale</literal> source checked is user&apos;s profile. + </para> + <procedure id="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_logged_in_users"> + <title>An algorithm for logged-in users</title> + <step> + <para> + Iterate over <literal>LocaleContextInfo</literal> properties in the following order: + </para> + <itemizedlist> + <listitem> + <para> + <literal>userProfile</literal> + </para> + </listitem> + <listitem> + <para> + <literal>cookieLocales</literal> + </para> + </listitem> + <listitem> + <para> + <literal>sessionLocale</literal> + </para> + </listitem> + <listitem> + <para> + <literal>browserLocales</literal> + </para> + </listitem> + <listitem> + <para> + <literal>portalLocale</literal> + </para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Perform the rest of the steps in <xref linkend="proc-Reference_Guide-Default_LocalePolicy-An_algorithm_for_anonymous_users"/>. + </para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Custom_LocalePolicy"> + <title>Custom LocalePolicy</title> + <para> + The easiest way to customize the <literal>LocalePolicy</literal> is to extend <literal>DefaultLocalePolicyService</literal>. A study of the source code is required. JavaDocs provide thorough information on this. + </para> + <para> + Most customizations will involve simply overriding one or more of its protected methods. + </para> + <para> + An example of a customization is an already provided <literal>NoBrowserLocalePolicyService</literal>. By overriding just one method, it skips any use of browser language preference. + </para> + <programlisting language="Java" role="Java">public class NoBrowserLocalePolicyService extends DefaultLocalePolicyService { /** * Override super method with no-op. @@ -231,63 +200,54 @@ } } </programlisting> - - </section> - - <section id="sect-Reference_Guide-Pluggable_Locale_Policy-LocalePolicy_Configuration"> - <title>LocalePolicy Configuration</title> - <para> - The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal's webui configuration file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: - </para> - -<programlisting language="XML" role="XML">&lt;application-life-cycle-listeners&gt; + </section> + <section id="sect-Reference_Guide-Pluggable_Locale_Policy-LocalePolicy_Configuration"> + <title><remark>BZ#794455 </remark>LocalePolicy Configuration</title> + <para> + The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal&apos;s webui configuration file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: + </para> + <programlisting language="XML" role="XML">&lt;application-life-cycle-listeners&gt; ... &lt;listener&gt;org.exoplatform.portal.application.localization.LocalizationLifecycle&lt;/listener&gt; &lt;/application-life-cycle-listeners&gt; </programlisting> - <para> - The default <literal>LocalePolicy</literal> implementation is installed as an eXo Kernel portal service via <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/lib/exo.portal.webui.portal-VERSION.jar/conf/portal/configuration.xml</filename>. - </para> - <para> - The following excerpt is responsible for installing the service: - </para> - -<programlisting language="XML" role="XML">&lt;component&gt; + <remark>BZ#794455 - 20120319 - Updated the location of LocalePolicy as prescribed.</remark> + <para> + The default <literal>LocalePolicy</literal> implementation is installed as an eXo Kernel portal service via <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/web-configuration.xml</filename>. + </para> + <para> + The following excerpt is responsible for installing the service: + </para> + <programlisting language="XML" role="XML">&lt;component&gt; &lt;key&gt;org.exoplatform.services.resources.LocalePolicy&lt;/key&gt; &lt;type&gt;org.exoplatform.portal.application.localization.DefaultLocalePolicyService&lt;/type&gt; &lt;/component&gt; </programlisting> - <para> - Besides implementing <literal>LocalePolicy</literal>, the service class also needs to implement <literal>org.picocontainer.Startable</literal> interface in order to get installed. - </para> - <para> - This configuration file should not be changed. The configuration in it can be overridden by placing it into portal's .war file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename> (usually as another file included into this one). - </para> - - </section> - - <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Keeping_non_bridged_resources_in_sync_with_current_Locale"> - <title>Keeping non-bridged resources in sync with current Locale</title> - <para> - All the resources in portals that are not portlets themselves, but are accessed through portlets - reading data through <literal>PortletRequest</literal>, and writing to <literal>PortletResponse</literal> - are referred to as 'bridged'. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as 'non-bridged'. - </para> - <para> - Non-bridged servlets, and .jsps have no access to <literal>PortalRequest</literal>. They don't use <literal>PortletRequest.getLocale()</literal> to determine current <literal>Locale</literal>. Instead, they use <literal>ServletRequest.getLocale()</literal> which is subject to precise semantics defined by Servlet specification - it reflects browser's language preference. - </para> - <para> - In other words, non-bridged resources do not have a notion of current <literal>Locale</literal> in the same sense that portlets do. The result is that when mixing portlets and non-bridged resources there may be a localization mismatch, an inconsistency in the language used by different resources composing your portal page. - </para> - <para> - This problem is addressed by <literal>LocalizationFilter</literal>. This is a filter that changes the behavior of <literal>ServletRequest.getLocale()</literal> method so that it behaves the same way as <literal>PortletRequest.getLocale()</literal>. - </para> - <para> - That way even localization of servlets, and .jsps accessed in a non-bridged manner can stay in sync with portlet localization. - </para> - <para> - <literal>LocalizationFilter</literal> is installed through the portal's web.xml file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. - </para> - -<programlisting language="XML" role="XML">&lt;filter&gt; + <para> + Besides implementing <literal>LocalePolicy</literal>, the service class also needs to implement <literal>org.picocontainer.Startable</literal> interface in order to get installed. + </para> + </section> + <section id="sect-Reference_Guide-Pluggable_Locale_Policy-Keeping_non_bridged_resources_in_sync_with_current_Locale"> + <title>Keeping non-bridged resources in sync with current Locale</title> + <para> + All the resources in portals that are not portlets themselves, but are accessed through portlets - reading data through <literal>PortletRequest</literal>, and writing to <literal>PortletResponse</literal> - are referred to as &apos;bridged&apos;. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as &apos;non-bridged&apos;. + </para> + <para> + Non-bridged servlets, and .jsps have no access to <literal>PortalRequest</literal>. They don&apos;t use <literal>PortletRequest.getLocale()</literal> to determine current <literal>Locale</literal>. Instead, they use <literal>ServletRequest.getLocale()</literal> which is subject to precise semantics defined by Servlet specification - it reflects browser&apos;s language preference. + </para> + <para> + In other words, non-bridged resources do not have a notion of current <literal>Locale</literal> in the same sense that portlets do. The result is that when mixing portlets and non-bridged resources there may be a localization mismatch, an inconsistency in the language used by different resources composing your portal page. + </para> + <para> + This problem is addressed by <literal>LocalizationFilter</literal>. This is a filter that changes the behavior of <literal>ServletRequest.getLocale()</literal> method so that it behaves the same way as <literal>PortletRequest.getLocale()</literal>. + </para> + <para> + That way even localization of servlets, and .jsps accessed in a non-bridged manner can stay in sync with portlet localization. + </para> + <para> + <literal>LocalizationFilter</literal> is installed through the portal&apos;s web.xml file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + </para> + <programlisting language="XML" role="XML">&lt;filter&gt; &lt;filter-name&gt;LocalizationFilter&lt;/filter-name&gt; &lt;filter-class&gt;org.exoplatform.portal.application.localization.LocalizationFilter&lt;/filter-class&gt; &lt;/filter&gt; @@ -303,11 +263,10 @@ &lt;dispatcher&gt;ERROR&lt;/dispatcher&gt; &lt;/filter-mapping&gt; </programlisting> - <para> - There is a minor limitation with this mechanism in that it is unable to determine the current portal,and consequently, its default language. As a result the portalLocale defaults to <literal>English</literal>, but can be configured to something else by using the filter's <literal>PortalLocale</literal> init param. For example: - </para> - -<programlisting language="XML" role="XML">&lt;filter&gt; + <para> + There is a minor limitation with this mechanism in that it is unable to determine the current portal,and consequently, its default language. As a result the portalLocale defaults to <literal>English</literal>, but can be configured to something else by using the filter&apos;s <literal>PortalLocale</literal> init param. For example: + </para> + <programlisting language="XML" role="XML">&lt;filter&gt; &lt;filter-name&gt;LocalizationFilter&lt;/filter-name&gt; &lt;filter-class&gt;org.exoplatform.portal.application.localization.LocalizationFilter&lt;/filter-class&gt; &lt;init-param&gt; @@ -316,24 +275,18 @@ &lt;/init-param&gt; &lt;/filter&gt; </programlisting> - <para> - By default, <literal>LocalizationFilter</literal> is applied very broadly to cover all the resources automatically. - </para> - <para> - JBoss Enterprise Portal Platform uses some non-bridged .jsps that require <literal>LocalizationFilter</literal>, so narrowing the mapping to *.jsp is enough for JBoss Enterprise Portal Platform to function correctly. - </para> - <para> - Additionally deployed portlets, and portal applications, however, may require broader mapping to cover their non-bridged resources. - </para> - <para> - Narrowing the mapping might improve performance. This is something to consider, when optimizing for speed. - </para> - - </section> - - - </section> - - + <para> + By default, <literal>LocalizationFilter</literal> is applied very broadly to cover all the resources automatically. + </para> + <para> + JBoss Enterprise Portal Platform uses some non-bridged .jsps that require <literal>LocalizationFilter</literal>, so narrowing the mapping to *.jsp is enough for JBoss Enterprise Portal Platform to function correctly. + </para> + <para> + Additionally deployed portlets, and portal applications, however, may require broader mapping to cover their non-bridged resources. + </para> + <para> + Narrowing the mapping might improve performance. This is something to consider, when optimizing for speed. + </para> + </section> + </section> </chapter> - Modified: epp/docs/branches/5.2/Reference_Guide/publican.cfg =================================================================== --- epp/docs/branches/5.2/Reference_Guide/publican.cfg 2012-03-20 03:15:39 UTC (rev 8618) +++ epp/docs/branches/5.2/Reference_Guide/publican.cfg 2012-03-20 04:35:30 UTC (rev 8619) @@ -1,13 +1,8 @@ -# Config::Simple 4.59 -# Tue Sep 27 14:25:48 2011 -cvs_root: ":ext:cvs.devel.redhat.com:/cvs/dist" -cvs_branch: "DOCS-RHEL-6" -#show_remarks: 1 -cvs_pkg: "JBoss_Enterprise_Portal_Platform-Reference_Guide-5.2-web-__LANG__" xml_lang: "en-US" brand: JBoss debug: 1 type: Book -#toc_section_depth: 10 -#generate_section_toc_level: 3 \ No newline at end of file +git_branch: docs-rhel-6 +show_remarks: 1 +