[gatein-commits] gatein SVN: r9077 - in epp/docs/branches/6.0/Reference_Guide/en-US: modules/Advanced/Foundations and 7 other directories.

Author: jaredmorgs Date: 2013-01-24 21:15:12 -0500 (Thu, 24 Jan 2013) New Revision: 9077 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.ent epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml Log: Removed all instances of 02portal and changed to just portal, updated file paths to portal.xml and portlet.xml, except when they related to portlet bridge. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.ent =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.ent 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Reference_Guide.ent 2013-01-25 02:15:12 UTC (rev 9077) @@ -17,4 +17,4 @@ <!ENTITY VX "6"> <!ENTITY VY "6.0"> <!ENTITY VZ "6.0.0"> -<!ENTITY WSRP_VERSION "CHANGEME"> +<!ENTITY WSRP_VERSION "2.2.2.Final"> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/Revision_History.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -275,7 +275,7 @@ <revdescription> <simplelist> <member>BZ#856417 - Added Examples to Portlet Bridge section from content in https://docs.jboss.org/author/display/PBR/Examples, and did a final review of content before submitting JSF2 and RF4 tasks for QE validation. </member> - <member>Also removed text references to JBoss Enterprise Portal Platform, Enterprise Portal Platform, EPP_HOME, and EPP_DIST.</member> + <member>Also removed text references to JBoss Enterprise Portal Platform, Enterprise Portal Platform, JPP_HOME, and JPP_DIST.</member> </simplelist> </revdescription> </revision> @@ -415,7 +415,7 @@ </author> <revdescription> <simplelist> - <member>Bug 850746 - Remove Chapter 41. eXo JCR Backup Service and Chapter 42. HTTPBackupAgent and Backup Client from EPP Reference Guide.</member> + <member>Bug 850746 - Remove Chapter 41. eXo JCR Backup Service and Chapter 42. HTTPBackupAgent and Backup Client from JPP Reference Guide.</member> </simplelist> </revdescription> </revision> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/Advanced/Foundations/Configuring_Services.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -21,7 +21,7 @@ All <filename>configuration.xml</filename> files located at <filename>conf/portal/configuration.xml</filename> in the classpath will have their services configured at the <literal>PortalContainer</literal> scope. </para> <para> - Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. + Additionally, <emphasis role="bold">portal extensions</emphasis> can use configuration information stored in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/configuration.xml</filename>, and will also have their services configured in the <literal>PortalContainer</literal> scope. </para> <para> When eXo kernel reads a configuration, it loads the file from the kernel jar using the classloader and does not use an internet connection to resolve the file. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/AuthenticationAuthorizationOverview.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -5,11 +5,7 @@ ]> <chapter id="sect-Reference_Guide-Authentication_Authorization_Intro"> <title>Authentication and Authorization intro</title> - <remark> - ======================================================= - NOTE: Content updated to wiki version 4 (11 Jan 2013) - =======================================================</remark> - + <remark> ======================================================= NOTE: Content updated to wiki version 4 (11 Jan 2013) =======================================================</remark> <section id="sect-Reference_Guide-Authentication_Authorization_Intro-Authentication"> <title>Authentication Overview</title> <para> @@ -32,19 +28,19 @@ <listitem> <remark>FIXME: Correct the following link</remark> <para> - SSO server integration (CAS, JOSSO, OpenSSO). Refer to ** xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/ for more information. + SSO server integration (CAS, JOSSO, OpenSSO). Refer to ** xref linkend=&quot;sect-Reference_Guide-SSO_Single_Sign_On&quot;/ for more information. </para> </listitem> <listitem> <remark>FIXME: Correct the following link</remark> <para> - SPNEGO authentication with a Kerberos ticket. Refer to ** xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/ for more information. + SPNEGO authentication with a Kerberos ticket. Refer to ** xref linkend=&quot;sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism&quot;/ for more information. </para> </listitem> <listitem> - <para> + <para> <remark>FIXME: Fix the following link</remark> - SAML2 based authentication. Refer to ** xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SAML2"/ for more information. + SAML2 based authentication. Refer to ** xref linkend=&quot;sect-Reference_Guide-SSO_Single_Sign_On_-SAML2&quot;/ for more information. </para> </listitem> <listitem> @@ -111,7 +107,7 @@ </mediaobject> </para> <para> - Changes to the appearance of this login page can be made in this JSP file. Alternatively you can create an extension and override this page via extension if you don't want to edit it directly. You can also change images or CSS placed in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . + Changes to the appearance of this login page can be made in this JSP file. Alternatively you can create an extension and override this page via extension if you don&apos;t want to edit it directly. You can also change images or CSS placed in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/login/skin</filename> . </para> <para> After a user submits the login form, they are redirected to the login URL: <ulink url="http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/classic" type="http">http://localhost:8080/portal/login?username=root&amp;password=gtn&amp;initialURI=/portal/private/classic</ulink>. @@ -128,9 +124,7 @@ <para> Below is the default login modules stack: </para> - <remark> - QUESTION: Does the reference below "JBossAS7LoginModule" need to be changed? - </remark> + <remark> QUESTION: Does the reference below &quot;JBossAS7LoginModule&quot; need to be changed? </remark> <programlisting language="XML" role="XML"><![CDATA[ <security-domain name="gatein-domain" cache-type="default"> <authentication> @@ -151,9 +145,9 @@ <para> New login modules can be added or the stack completely replaced with custom modules. </para> - <remark>QUESTION: Should the following reference be to official Red Hat documentation instead of Oracle's?</remark> + <remark>QUESTION: Should the following reference be to official Red Hat documentation instead of Oracle&apos;s?</remark> <para> - Authentication starts with the login method of each login module being invoked. After all login methods are invoked, the authentication is continued by invoking the commit method on each login module. Both login and commit methods can throw LoginException. If it happens, then the whole authentication ends unsuccessfully, which in turn invokes the abort method on each login module. By returning "false" from the login method, you can ensure that the login module is ignored. This is not specific to JBoss Portal Platform but it is generic to JAAS. Refer to <ulink type="http" url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... here for more information about login modules in general. + Authentication starts with the login method of each login module being invoked. After all login methods are invoked, the authentication is continued by invoking the commit method on each login module. Both login and commit methods can throw LoginException. If it happens, then the whole authentication ends unsuccessfully, which in turn invokes the abort method on each login module. By returning &quot;false&quot; from the login method, you can ensure that the login module is ignored. This is not specific to JBoss Portal Platform but it is generic to JAAS. Refer to <ulink url="http://docs.oracle.com/javase/6/docs/technotes/guides/security/... type="http">http://docs.oracle.com/javase/6/docs/technotes/g... here for more information about login modules in general. </para> <section id="sect-Authentication_Authorization_Intro-existingLM"> <title>Existing login modules</title> @@ -167,7 +161,7 @@ <listitem> <remark>FIXME: Fix the link to the relevant CAS section</remark> <para> - It's useful only if SSO authentication is enabled (disabled by default. It can be enabled through properties in configuration.properties file and in this case it delegates the work to another real login module for SSO integration. If SSO is disabled, SSODelegateLoginModule is simply ignored. See ** xref linkend="Central Authentication Service (CAS)#Configuration"/ properties details for more details. If SSO is used and SSO authentication succeed, the special Identity object will be created and saved into shared state map (Map, which is shared between all login modules), so that this Identity object can be used by JBossAS7LoginModule or other login modules in the JAAS chain. + It&apos;s useful only if SSO authentication is enabled (disabled by default. It can be enabled through properties in configuration.properties file and in this case it delegates the work to another real login module for SSO integration. If SSO is disabled, SSODelegateLoginModule is simply ignored. See ** xref linkend=&quot;Central Authentication Service (CAS)#Configuration&quot;/ properties details for more details. If SSO is used and SSO authentication succeed, the special Identity object will be created and saved into shared state map (Map, which is shared between all login modules), so that this Identity object can be used by JBossAS7LoginModule or other login modules in the JAAS chain. </para> </listitem> </varlistentry> @@ -180,11 +174,9 @@ </listitem> </varlistentry> </variablelist> - <para> Some other login modules are not active by default, but can be added them if you find them useful. </para> - <variablelist> <varlistentry> <term>CustomMembershipLoginModule</term> @@ -193,32 +185,31 @@ Special login module, which can be used to add a user to existing groups during a successful login of this user. The group name is configurable and by default is /platform/users group. This login module is not used because in normal environment, users are already in the /platform/users group. It is useful only for some special setups like read-only LDAP, where groups of an LDAP user are taken from the LDAP tree so that users may not be in the /platform/users group, which is needed for successful authorization. </para> <para> - Note that the CustomMembershipLoginModule can't be the first login module in the LoginModule chain because it assumes that the Identity object is already available in shared state. So there are two possible cases. For an non-SSO case, you may need to chain this LM with other login modules, which can be used to establish Identity and add it into shared state. Those LM can be InitSharedStateLoginModule and SharedStateLoginModule. For an SSO case, you can add CustomMembershipLoginModule between SSODelegateLoginModule and JBossAS7LoginModule. + Note that the CustomMembershipLoginModule can&apos;t be the first login module in the LoginModule chain because it assumes that the Identity object is already available in shared state. So there are two possible cases. For an non-SSO case, you may need to chain this LM with other login modules, which can be used to establish Identity and add it into shared state. Those LM can be InitSharedStateLoginModule and SharedStateLoginModule. For an SSO case, you can add CustomMembershipLoginModule between SSODelegateLoginModule and JBossAS7LoginModule. </para> </listitem> </varlistentry> <varlistentry> - <term>InitSharedStateLoginModule</term> - <listitem> - <para> - It can read credentials from JAAS callback and add them into shared state. It's intended to be used in JAAS chain before SharedStateLoginModule + <term>InitSharedStateLoginModule</term> + <listitem> + <para> + It can read credentials from JAAS callback and add them into shared state. It&apos;s intended to be used in JAAS chain before SharedStateLoginModule </para> - </listitem> + </listitem> </varlistentry> <varlistentry> - <term>SharedStateLoginModule</term> - <listitem> - <para> + <term>SharedStateLoginModule</term> + <listitem> + <para> It reads username and password from sharedState map from attributes javax.security.auth.login.name and javax.security.auth.login.password. Then it calls Authenticator.validateUser(Credential[] credentials), to perform authentication of username and password against OrganizationService and portal identity database. Result of successful authentication is object Identity, which is saved to sharedState map. </para> - </listitem> + </listitem> </varlistentry> </variablelist> - <para> Configuration example with CustomMembershipLoginModule and disabled SSO: </para> - <programlisting language="XML" role="XML"><![CDATA[ + <programlisting language="XML" role="XML"><![CDATA[ <login-module code="org.exoplatform.web.security.InitSharedStateLoginModule" flag="required"> <module-option name="portalContainerName" value="portal"/> <module-option name="realmName" value="gatein-domain"/> @@ -238,12 +229,10 @@ <module-option name="realmName" value="gatein-domain"/> </login-module>]]> </programlisting> - <para> And a configuration example with enabled SSO: </para> - - <programlisting language="XML" role="XML"><![CDATA[ + <programlisting language="XML" role="XML"><![CDATA[ <login-module code="org.gatein.sso.integration.SSODelegateLoginModule" flag="required"> <module-option name="enabled" value="${gatein.sso.login.module.enabled}" /> <module-option name="delegateClassName" value="${gatein.sso.login.module.class}" /> @@ -262,11 +251,8 @@ <module-option name="realmName" value="gatein-domain"/> </login-module>]]> </programlisting> - - </section> -<!-- Ending section with existing login modules --> - <section id="sect-Authentication_Authorization_Intro-createNewLM"> +<!-- Ending section with existing login modules --> <section id="sect-Authentication_Authorization_Intro-createNewLM"> <title>Creating your own login module</title> <para> Before creating your own login module, it is recommended that you study the source code of existing login modules to better understand the JAAS authentication process. You need to have good knowledge so that you can properly decide where your login module should be placed and if you need to replace some existing login modules or simply attach your own module to the existing chain. @@ -303,8 +289,7 @@ </para> </formalpara> </section> -<!-- Ending section with your own login module --> - <section id="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"> +<!-- Ending section with your own login module --> <section id="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"> <title>Authenticator and RolesExtractor</title> <para> Authenticator is an important component in the authentication process. The interface <emphasis>org.exoplatform.services.security.Authenticator</emphasis> looks like this: @@ -439,7 +424,7 @@ <section id="sect-Authentication_Authorization_Intro-RememberMeAuthentication-RemindPasswordTokenService"> <title>RemindPasswordTokenService</title> <para> - This is a special service used during the RememberMe authentication workflow. It is configurable in the file <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration"/> + This is a special service used during the RememberMe authentication workflow. It is configurable in the file <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/common/remindpwd-configuration.xml</filename> . For more info, look at section <xref linkend="sect-Reference_Guide-Authentication_Token_Configuration"/> </para> <para> You can encrypt passwords before storing them in JCR. More info is in section <xref linkend="sect-Reference_Guide-Authentication_and_Identity-Password_Encryption"/>. @@ -447,73 +432,73 @@ </section> </section> <section id="sect-Authentication_Authorization_Intro-authorization"> - <title>Authorization overview</title> - <para> + <title>Authorization overview</title> + <para> In the previous section, you learned about JAAS authentication and about login modules. So you know the result of authentication, including: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> JAAS Subject with principals for username (UserPrincipal) and for JAAS roles (RolesPrincipal). </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Identity object, which encapsulates username, all memberships and all JAAS roles. This Identity object is bound to IdentityRegistry component. </para> - </listitem> - </itemizedlist> - <para> + </listitem> + </itemizedlist> + <para> Authorization in JBoss Portal Platform actually happens on two levels: </para> - <section id="sect-Authentication_Authorization_Intro-servletContainerAuthorization"> - <title>Servlet container authorization</title> - <para> + <section id="sect-Authentication_Authorization_Intro-servletContainerAuthorization"> + <title>Servlet container authorization</title> + <para> First round of authorization is servlet container authorization based on secured URL from <filename>web.xml</filename>. We saw above in web.xml snippet that secured URL are accessible only for users from role <emphasis>users</emphasis>: </para> - <programlisting language="XML" role="XML"><![CDATA[ + <programlisting language="XML" role="XML"><![CDATA[ <auth-constraint> <role-name>users</role-name> </auth-constraint>]]></programlisting> - <remark>FIXME: correct the link to 'Login modules'</remark> - <para> + <remark>FIXME: correct the link to &apos;Login modules&apos;</remark> + <para> This actually means that our user needs to be in JBoss Portal Platform role <emphasis>/platform/users</emphasis> (For details see <xref linkend="sect-Authentication_Authorization_Intro-authenticatorAndRolesExtractor"/>). In other words, if we successfully authenticate but our user is not in group <emphasis>/platform/users</emphasis>, then it means that he is not in JAAS role <emphasis>users</emphasis>, which in turn means that they will have authorization error <emphasis role="bold">403 Forbidden</emphasis> thrown by servlet container. For example in LDAP setup, your users may not be in /platform/users by default, but you can use CustomMembershipLoginModule to fix this problem. For details see ** Login modules**. </para> - <para> + <para> You can change the behavior and possibly add some more <emphasis>auth-constraint</emphasis> elements into <filename>web.xml</filename>. However this protection of resources based on web.xml is not standard JBoss Portal Platform method and is mentioned here mainly for illustration purposes. </para> - </section> - <section id="sect-Authentication_Authorization_Intro-gateInAuthorization"> - <title>Portal level authorization</title> - <para> + </section> + <section id="sect-Authentication_Authorization_Intro-gateInAuthorization"> + <title>Portal level authorization</title> + <para> The second round of authorization is based on the component <emphasis role="bold">UserACL</emphasis> (See <xref linkend="chap-Reference_Guide-Portal_Default_Permission_Configuration"/>). You can declare access and edit permissions for portals, pages and/or portlets. UserACL is then used to check if our user has particular permissions to access or edit specified resources. An important object containing information about the roles of our user is the <emphasis>Identity</emphasis> object created during JAAS authentication. </para> - <para> + <para> Authorization on portal level looks like this: </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> The user sends a HTTP request to some URLs in portal; </para> - </listitem> - <listitem> - <para> - The HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + </listitem> + <listitem> + <para> + The HTTP request is processed through <literal>SetCurrentIdentityFilter</literal>, which is declared in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/web.xml</filename>. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> SetCurrentIdentityFilter reads username of current user from <emphasis>HttpServletRequest.getRemoteUser()</emphasis>. Then it looks for Identity of this user in IdentityRegistry, where Identity has been saved during authentication. The Identity found is then encapsulated into a <emphasis role="bold">ConversationState</emphasis> object and bound into the ThreadLocal variable. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> UserACL is able to obtain Identity of current user from method <emphasis>UserACL.getIdentity()</emphasis>, which simply calls <emphasis>ConversationState.getCurrent().getIdentity()</emphasis> to find the current Identity bound to ThreadLocal. Now the UserACL has the identity of the user and can perform any security checks. </para> - </listitem> - </itemizedlist> + </listitem> + </itemizedlist> + </section> </section> </section> - </section> <!-- Ending section Authorization overview --></chapter> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/CoreOrganizationInitializer.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -8,11 +8,11 @@ <para>The plug-in is particularly useful when using the Site Publisher add-on, and directly adding users or groups to a LDAP server through LDIF files, or into a database using SQL. </para> <section> <title>Enable Initializer</title> - <para>The initializer is disabled by default. To activate it, uncomment the block containing the path to the <filename>initializer-configuration.xml</filename> file in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/configuration.xml</filename>. + <para>The initializer is disabled by default. To activate it, uncomment the block containing the path to the <filename>initializer-configuration.xml</filename> file in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/configuration.xml</filename>. </para> <programlisting language="XML">&lt;!-- Uncomment for enable initializer (OrganizationListenersInitializerService and related stuff) --&gt; &lt;import&gt;war:/conf/organization/initializer-configuration.xml&lt;/import&gt;</programlisting> - <para>All configuration for the initializer occurs in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename>, which is the main configuration file + <para>All configuration for the initializer occurs in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/organization/initializer-configuration.xml</filename>, which is the main configuration file for this initializer. More details about configuration options, along with alternatives to XML directive configuration, are described in subsequent sections.</para> </section> <section> @@ -79,7 +79,7 @@ </section> <section id="Triggering_Operations"> <title>Using configuration directives</title> - <para>There are a number of ways of controlling operations associated with CoreOrganizationInitializer. All parameters are configured in &lt;value-param&gt; directive blocks in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename> file.</para> + <para>There are a number of ways of controlling operations associated with CoreOrganizationInitializer. All parameters are configured in &lt;value-param&gt; directive blocks in the <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/organization/initializer-configuration.xml</filename> file.</para> <example> <title>&lt;value-param&gt; block for initializer directives</title> <programlisting language="XML">&lt;value-param&gt; @@ -91,7 +91,7 @@ <title>Disable launchAll at Startup</title> <para>For large implementations with many users and groups, consider disabling <parameter>launchAll</parameter> functionality during start-up for each portal container. Disabling this operation during start-up will result in a performance improvement.</para> <step> - <para>Open <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Locate the <parameter>executeAllListenersDuringBoot</parameter> &lt;value-param&gt; parameter.</para> @@ -104,7 +104,7 @@ <title>Disable launchAll Job Scheduler</title> <para>A job scheduler is configured to run by default, and executes <parameter>launchAll</parameter> periodically. For large implementations with many users and groups, consider disabling the Job scheduler <parameter>launchAll</parameter> functionality for each portal container. Disabling this operation may result in a performance improvement.</para> <step> - <para>Open <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Search for &quot;scheduler&quot; in the file.</para> @@ -117,7 +117,7 @@ <title>Alter the way JCR objects are created on-demand, at user login. </title> <para>When a user logs into the portal, the <parameter>treatUser</parameter> operation runs on-demand to create the required JCR objects. This operation (activated by default) improves overall performance of the portal, because user objects are only created when needed. To disable the operation (not recommended), follow the guidelines below.</para> <step> - <para>Open <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/conf/organization/initializer-configuration.xml</filename></para> + <para>Open <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/conf/organization/initializer-configuration.xml</filename></para> </step> <step> <para>Locate the <parameter>ExtensibleFilter</parameter> directive block.</para> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PasswordEncryption.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -139,7 +139,7 @@ <orderedlist> <listitem> <para> - The <emphasis>Remember Me</emphasis> feature can be disabled by removing the corresponding checkbox in: <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/login/jsp/login.jsp</filename> and <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename>. + The <emphasis>Remember Me</emphasis> feature can be disabled by removing the corresponding checkbox in: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/login/jsp/login.jsp</filename> and <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/groovy/portal/webui/UILoginForm.gtmpl</filename>. </para> </listitem> <listitem> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/PredefinedUserConfiguration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Predefined_User_Configuration-Overview"> <title>Overview</title> <para> - The initial Organization configuration should be specified by editing the content of <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. + The initial Organization configuration should be specified by editing the content of <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war:/WEB-INF/conf/organization/organization-configuration.xml</filename>. This file uses the portal XML configuration schema. It lists several configuration plug-ins. </para> </section> <section id="sect-Reference_Guide-Predefined_User_Configuration-Plugin_for_adding_users_groups_and_membership_types"> @@ -33,7 +33,7 @@ </para> <note> <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + See <literal><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. </para> </note> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default98.xml" parse="text"/></programlisting> @@ -45,7 +45,7 @@ </para> <note> <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + See <literal>JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. </para> </note> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default99.xml" parse="text"/></programlisting> @@ -57,7 +57,7 @@ </para> <note> <para> - See <literal>02portal.war:/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. + See <literal><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/organization-configuration.xml</literal> for the full content. </para> </note> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_PredefinedUserConfiguration/default100.xml" parse="text"/></programlisting> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -1,311 +1,250 @@ <?xml version='1.0' encoding='UTF-8'?> -<!-- This document was created with Syntext Serna Free. --> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!-- This document was created with Syntext Serna Free. --><!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="sect-Reference_Guide-SSO_Single_Sign_On"> - <title>Single Sign-On</title> - - <section id="sect-SSO_Single_Sign_On_-Overview"> - <title>Overview and Configuration Assumptions</title> - - <para> +<chapter id="sect-Reference_Guide-SSO_Single_Sign_On"> + <title>Single Sign-On</title> + <section id="sect-SSO_Single_Sign_On_-Overview"> + <title>Overview and Configuration Assumptions</title> + <para> JBoss Portal Platform provides an implementation of single sign-on (<literal>SSO</literal>) as an integration and aggregation platform. </para> - - <para> + <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 Portal Platform: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> <xref linkend="sect-SSO_Single_Sign_On_-Central_Authentication_Service"/> </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"/> </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM"/> </para> - </listitem> - - <listitem> - <para> + </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> + </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 the <filename><filename>JPP_DIST</filename>/gatein-sso</filename> directory of the JBoss Portal Platform binary package. </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 <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-SSO_Single_Sign_On_-Central_Authentication_Service"> - <title><remark>BZ#856430</remark>Central Authentication Service (CAS)</title> - - <para> + </para> --> </warning> + </section> + <section id="sect-SSO_Single_Sign_On_-Central_Authentication_Service"> + <title><remark>BZ#856430</remark>Central Authentication Service (CAS)</title> + <para> The CAS single sign-on (SSO) plug-in enables seamless integration between the platform and the CAS SSO framework. General information about CAS can be found on the <ulink url="http://www.jasig.org/cas">Jasig website</ulink>. </para> - - <section id="sect-CAS-Authentication_Process"> - <title>Authentication Process</title> - - <para> + <section id="sect-CAS-Authentication_Process"> + <title>Authentication Process</title> + <para> The authentication process with CAS integration occurs in the following order: </para> - - <orderedlist> - <listitem> - <para> + <orderedlist> + <listitem> + <para> A user visits the main portal page, and wishes to authenticate. The user clicks <emphasis role="italics">Sign in</emphasis>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Normally this action would present the portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as <ulink url="http://localhost:8080/portal/sso"/>. </para> - - <para> + <para> The portal handles this user action by calling the interceptor (Servlet filter) <emphasis role="strong">LoginRedirectFilter</emphasis>, which redirects the user seamlessly away from the <emphasis role="italics">/portal/sso</emphasis> URL to the CAS server page. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The interceptor redirects the user to the CAS login page <ulink url="http://localhost:8888/cas/login"/> . The user enters the correct authentication information, and submits the form. </para> - - <para> + <para> The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with JBoss Portal Platform. Refer to <xref linkend="sect-CAS_Authentication_Plug-in"/> for specific details about this technology. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as <ulink url="http://localhost:8080/portal/initiatelogin"/> . </para> - - <para> + <para> The <emphasis role="strong">InitiateLoginFilter</emphasis> interceptor acts on the user redirection to <emphasis role="italics">/portal/initiatelogin</emphasis> by obtaining a CAS ticket attached in the HTTP request inside the <emphasis role="italics">ticket</emphasis> parameter. The interceptor then delegates validation of this ticket to a configured <emphasis role="strong">CASAgent</emphasis> component. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <emphasis>CASAgent</emphasis> validates the ticket by sending a validation request to the CAS server through a configured back channel. The CAS server validates the request, and ensures it contains the user name of the authenticated user in step 3. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> After SSO validation, <emphasis role="italics">InitiateLoginFilter</emphasis> redirects the user to the portal login URL <ulink url="http://localhost:8080/portal/login"/> , which initiates JAAS authentication. </para> - - <para> + <para> The <emphasis role="strong">SSOLoginModule</emphasis> detects whether the user has been successfully validated by <emphasis role="italics">CASAgent</emphasis>. If this is the case, the login module obtains data about user (groups, memberships) from <emphasis role="italics">OrganizationService</emphasis> and encapsulates the details into an <emphasis role="strong">Identity</emphasis> object. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <emphasis role="strong">JBossAS7LoginModule</emphasis> completes the authentication request by establishing the JAAS <emphasis role="italics">Subject</emphasis>, and saves the <emphasis role="italics">Identity</emphasis> object to the <emphasis role="italics">IdentityRegistry</emphasis>. For more information about login modules, refer to <xref linkend="sect-Authentication_Authorization_Intro-Login_Modules"/>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> After successful JAAS authentication, the user is redirected to the portal in an authenticated state. </para> - </listitem> - </orderedlist> - - <para> + </listitem> + </orderedlist> + <para> For more information about the available Login Modules shipped with the product, refer to the JBoss Enterprise Application Platform <citetitle>Security Guide</citetitle>. </para> - </section> - - <section id="sect-CAS-Logout_Workflow"> - <title>Logout Process</title> - - <para> + </section> + <section id="sect-CAS-Logout_Workflow"> + <title>Logout Process</title> + <para> The logout process with CAS integration occurs in the following order: </para> - - <orderedlist> - <listitem> - <para> + <orderedlist> + <listitem> + <para> The authenticated user clicks the <emphasis role="italics">Sign out</emphasis> link. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <emphasis role="strong">CASLogoutFilter</emphasis> interceptor recognizes the logout request, and redirects the user to the CAS logout page <ulink url="http://localhost:8888/cas/logout"/> . </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The CAS server logs out the user, and invalidate the CAS cookie <emphasis role="italics">CASTGC</emphasis> . </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> CAS redirects the user back to the portal using the logout redirection configured in <xref linkend="sect-CAS_Logout_Redirection"/> . </para> - - <para> + <para> If the <emphasis role="italics">CASLogoutFilter</emphasis> is enabled, the user is logged out from both the portal and CAS server. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The logout redirection request completes the logout process on the CAS server&apos;s side, and the user is redirected to the portal&apos;s anonymous page. </para> - </listitem> - </orderedlist> - </section> - - <section id="sect-CAS-Configuration_Overview"> - <title>CAS Configuration Overview</title> - - <para> + </listitem> + </orderedlist> + </section> + <section id="sect-CAS-Configuration_Overview"> + <title>CAS Configuration Overview</title> + <para> For scope purposes, the setup instructions assume the following configuration outcomes: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> The CAS 3.5 is downloaded, and required changes are made to authentication plug-in, logout redirection, and CASTGC cookie configuration. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Once configured, Apache Maven is used to create the custom CAS web archive, suitable for deployment. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The WAR is deployed to the Apache Tomcat server, which acts as the host for the CAS. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Apache Tomcat is configured to listen on <emphasis role="italics">localhost:8888</emphasis>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> JBoss Portal Platform is configured to listen on <emphasis role="italics">localhost:8080</emphasis>. </para> - </listitem> - </itemizedlist> - - <section id="sect-CAS-Download_CAS"> - <title><remark>BZ#856430 </remark>Download CAS</title> - - <para> + </listitem> + </itemizedlist> + <section id="sect-CAS-Download_CAS"> + <title><remark>BZ#856430 </remark>Download CAS</title> + <para> CAS can be downloaded from <ulink url="http://www.jasig.org/cas/download"/> . The supported version is <emphasis role="italics">CAS 3.5</emphasis> . More recent CAS versions may also work, however have not been officially tested as part of this specific configuration exercise. </para> - <remark>Docs Note - jmorgan - Marek, I originally incorrectly specified that an admin should extract the CAS source binary into the Tomcat server. It&apos;s my fault, because I didn&apos;t realise that you need to configure CAS first, *then* build the WAR, and finally deploy to Tomcat. The following sentence makes this much clearer now.</remark> - <para> + <remark>Docs Note - jmorgan - Marek, I originally incorrectly specified that an admin should extract the CAS source binary into the Tomcat server. It&apos;s my fault, because I didn&apos;t realise that you need to configure CAS first, *then* build the WAR, and finally deploy to Tomcat. The following sentence makes this much clearer now.</remark> + <para> Extract the downloaded file into a suitable working directory. This location will be referred to as <code>CAS_DIR</code> in subsequent configuration instructions. </para> - </section> - </section> - - <section id="sect-CAS-Modifying_CAS_Server"> - <title>Modifying the CAS server</title> - - <para> + </section> + </section> + <section id="sect-CAS-Modifying_CAS_Server"> + <title>Modifying the CAS server</title> + <para> To configure the CAS server correctly, the most effective way is to make the necessary changes directly in the CAS code base. Follow the instructions in the sections below to make the required changes to the CAS code base, before using Maven to build the CAS web archive. </para> - - <section id="sect-CAS_Authentication_Plug-in"> - <title>Authentication Plug-in</title> - - <para> + <section id="sect-CAS_Authentication_Plug-in"> + <title>Authentication Plug-in</title> + <para> While it is possible (and perfectly acceptable) for an administrator to configure CAS to retrieve user credentials from an external database, or from a LDAP server, it is also possible to use JBoss technology. </para> - - <para> + <para> CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS <literal>AuthenticationPlugin</literal>. </para> - - <para> + <para> Implementing the <literal>AuthenticationPlugin</literal> on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the <literal>AuthenticationPlugin</literal>. </para> - - <para> + <para> The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal&apos;s own identity storage provided by the PicketLink IDM <emphasis role="italics">OrganizationService</emphasis>. The <literal>AuthenticationPlugin</literal> receives the portal&apos;s response to the CAS server, and continues with the authentication process based on user data in the response. </para> - - <para> + <para> For the plug-in to function correctly, it must be properly configured on the CAS server to connect to this service. Set up the server to authenticate against the portal using the REST call-back. </para> - - <procedure> - <title>Configuring the Authentication plug-in</title> - - <step> - <para> + <procedure> + <title>Configuring the Authentication plug-in</title> + <step> + <para> Open <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</code>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Replace the default configuration, which declares the Jasig <classname>SimpleTestUsernamePasswordAuthenticationHandler</classname> Authentication Handler with the following supported Authentication Handler. </para> - - <note> - <para> + <note> + <para> This configuration is available in the <code><replaceable>JPP_DIST</replaceable>gatein-sso/cas/plugin/WEB-INF/deployerConfigContext.xml</code> file. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. </para> - </note> -<programlisting> + </note> + <programlisting> &lt;!-- XML comment used for configuration guidance removed for ease of readability+--&gt; &lt;bean class=&quot;org.gatein.sso.cas.plugin.AuthenticationPlugin&quot;&gt; @@ -316,189 +255,152 @@ &lt;property name=&quot;httpMethod&quot;&gt;&lt;value&gt;POST&lt;/value&gt;&lt;/property&gt; &lt;/bean&gt; </programlisting> - </step> - - <step> - <para> + </step> + <step> + <para> Copy all jars from <code><replaceable>JPP_DIST</replaceable>gatein-sso/cas/plugin/WEB-INF/lib/</code> to the <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/lib</code> directory. </para> - </step> - </procedure> - </section> - - <section id="sect-CAS_Logout_Redirection"> - <title>Logout redirection setup</title> - - <para> + </step> + </procedure> + </section> + <section id="sect-CAS_Logout_Redirection"> + <title>Logout redirection setup</title> + <para> The CAS server displays the CAS logout page with a link to return to the portal by default. To make the CAS server redirect to the portal page after a logout, modify <code>CAS_DIR/cas-server-webapp/src/main/webapp/</code> <code>WEB-INF/cas-servlet.xml</code> to include the <code>followServiceRedirects=&quot;true&quot;</code> parameter: </para> -<programlisting language="">&lt;bean id=&quot;logoutController&quot; class=&quot;org.jasig.cas.web.LogoutController&quot; + <programlisting language="">&lt;bean id=&quot;logoutController&quot; class=&quot;org.jasig.cas.web.LogoutController&quot; p:centralAuthenticationService-ref=&quot;centralAuthenticationService&quot; p:logoutView=&quot;casLogoutView&quot; p:warnCookieGenerator-ref=&quot;warnCookieGenerator&quot; p:ticketGrantingTicketCookieGenerator-ref=&quot;ticketGrantingTicketCookieGenerator&quot; p:followServiceRedirects=&quot;true&quot;/&gt; </programlisting> - </section> - - <section id="sect-CAS_SSO_Cookie_Configuration"> - <title>CAS SSO cookie configuration (CASTGC)</title> - - <para> + </section> + <section id="sect-CAS_SSO_Cookie_Configuration"> + <title>CAS SSO cookie configuration (CASTGC)</title> + <para> Jasic CAS uses a cookie named - <firstterm> - CAS Ticket Granting Cookie - </firstterm> + <firstterm> CAS Ticket Granting Cookie </firstterm> (CASTGC) to control the authentication state within the browser session. The cookie contains a Ticket Granting Ticket (TGT), which preserves SSO authentication where more than one site is controlled by the same SSO profile. </para> - - <example id="exam-CASTGC_Authentication"> - <title>Basic CASTGC Portal Authentication Scenario</title> - - <para> + <example id="exam-CASTGC_Authentication"> + <title>Basic CASTGC Portal Authentication Scenario</title> + <para> Two portal servers are provisioned that use a single CAS server to manage authentication. The portals are named <literal>accounts</literal> and <literal>services</literal>. </para> - - <para> + <para> When a user initially accesses the <literal>accounts</literal> portal, they provide their SSO credentials, and CAS authenticates them as a registered user. The user then switches to the <literal>services</literal> portal, and is authenticated when she clicks the Sign in link. </para> - - <para> + <para> This behavior is correct given this example because the browser instance stores the browser authentication state using the CASTCG cookie. The CASTCG cookie in this instance creates new ticket for the <literal>services</literal> portal automatically based on the authentication state present for the accounts portal. </para> - </example> - - <para> + </example> + <para> The behavior described in <xref linkend="exam-CASTGC_Authentication"/>exists through a secured connection only (https connection). To benefit from authentication across two or more portals, one of the options below must be implemented. Choose the correct option based on the deployment environment: </para> - - <variablelist> - <varlistentry> - <term>Testing</term> - - <listitem> - <para> + <variablelist> + <varlistentry> + <term>Testing</term> + <listitem> + <para> Alter the CASTGC cookie to be non-secure. </para> - - <para> + <para> The cookie can be accessed through http (insecure) connections. </para> - - <para> + <para> To configure this test behavior, open <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml</code> and switch the attribute <code>cookieSecure</code> to false. </para> -<programlisting>&lt;bean id=&quot;ticketGrantingTicketCookieGenerator&quot; + <programlisting>&lt;bean id=&quot;ticketGrantingTicketCookieGenerator&quot; p:cookieSecure=&quot;false&quot; p:cookieMaxAge=&quot;-1&quot; p:cookieName=&quot;CASTGC&quot; p:cookiePath=&quot;/cas&quot; /&gt;</programlisting> - </listitem> - </varlistentry> - - <varlistentry> - <term>Production</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>Production</term> + <listitem> + <para> Correctly implement the https protocol for all production servers that rely on CAS. This configuration is the recommended method for any production server, and ensures greater security for CAS connections. Refer to the Jasig documentation about securing CAS <ulink url="https://wiki.jasig.org/display/CASUM/Securing+Your+New+CAS+Server "/> for information and resources. </para> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - - <section id="sect-CAS-Install_Tomcat_Server"> - <title>Install Apache Tomcat Server</title> - - <para> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section id="sect-CAS-Install_Tomcat_Server"> + <title>Install Apache Tomcat Server</title> + <para> Install and configure Apache Tomcat 7, which provides the host server for the CAS server. </para> - - <para> + <para> File name abbreviations in this section are described in <xref linkend="sect-File_Name_Conventions"/> </para> - - <procedure> - <title>Configuring Apache Tomcat for CAS</title> - - <step> - <para> + <procedure> + <title>Configuring Apache Tomcat for CAS</title> + <step> + <para> Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Extract and install the binary on the server that is required to host CAS. This directory is now referred to as <replaceable>TOMCAT_HOME</replaceable>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change port 8080 to 8888 to avoid a conflict with the default JBoss Portal Platform listen port. </para> - <remark>BZ#856430 - jmorgan - Added the new ports from the Confluence SSO Server Setup section</remark> - <important> - <para> + <remark>BZ#856430 - jmorgan - Added the new ports from the Confluence SSO Server Setup section</remark> + <important> + <para> If the Apache Tomcat server is installed on the same machine as JBoss Portal Platform, ensure other listen ports common to both servers are changed to prevent configuration issues. For example, change the Tomcat admin port from 8005 to 8805, and the Tomcat AJP port from 8009 to 8809. </para> - </important> - </step> - - <step> - <para> + </important> + </step> + <step> + <para> Ensure all Apache Tomcat ports are open in the server firewall, and the service is enabled and running so the platform can communicate with Apache Tomcat on the same server. </para> - </step> - </procedure> - </section> - - <section id="sect-CAS-Modifying_the_Portal"> - <title>Modifying the Portal</title> - - <para> + </step> + </procedure> + </section> + <section id="sect-CAS-Modifying_the_Portal"> + <title>Modifying the Portal</title> + <para> Before building and deploying the Jasig CAS sever, configuration needs to be implemented on the JBoss Portal Platform server to prepare the portal for CAS integration. </para> - - <section id="sect-CAS_Portal_SSO_Primary_Configuration_File"> - <title>Portal SSO Primary Configuration File</title> - - <para> + <section id="sect-CAS_Portal_SSO_Primary_Configuration_File"> + <title>Portal SSO Primary Configuration File</title> + <para> The main portal configuration file for SSO integration is <code>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/conf/sso/security-sso-configuration.xml</code> . All required SSO components such as agents and SSO interceptors (servlet filters in v5.x of the product) are configured in this file. </para> - - <para> + <para> In most cases, it will never be necessary to edit <filename>security-sso-configuration.xml</filename> directly when using JBoss Portal Platform. The portal architecture allows users to override the base configuration described in this file using name/value pairs configured in one place: <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> </para> - - <para> + <para> The exception to this rule is where configuration present in <filename>security-sso-configuration.xml</filename> is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor). </para> - </section> - - <section id="sect-CAS_Configuring_the_Platform"> - <title>Portal configuration.properties for CAS SSO</title> - - <para> + </section> + <section id="sect-CAS_Configuring_the_Platform"> + <title>Portal configuration.properties for CAS SSO</title> + <para> To prepare the portal platform for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, also needs to be specified. </para> - - <procedure> - <title>Configuring SSO configuration.properties for CAS</title> - - <step> - <para> + <procedure> + <title>Configuring SSO configuration.properties for CAS</title> + <step> + <para> Open <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> and locate the SSO sections in the file. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. </para> -<programlisting> + <programlisting> # SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} @@ -510,342 +412,281 @@ gatein.sso.filter.logout.url=${gatein.sso.server.url}/logout gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/login?service=${gatein.sso.portal.url}/@@[portal.container.name]@(a)/initiatessologin </programlisting> - </step> - </procedure> - - <variablelist> - <varlistentry> - <term>gatein.sso.enabled</term> - - <listitem> - <para> + </step> + </procedure> + <variablelist> + <varlistentry> + <term>gatein.sso.enabled</term> + <listitem> + <para> Specifies whether SSO integration is enabled on the portal. With this option set to &quot;true&quot; when a user clicks the <emphasis role="italics">Sign in</emphasis> link, the user is redirected to the <emphasis role="italics">/portal/sso</emphasis> URL rather than a standard Sign in dialog. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.callback.enabled</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.callback.enabled</term> + <listitem> + <para> Specifies whether the REST callback authentication handler is enabled. </para> - - <para> + <para> The handler is required if the CAS server must use the SSO Authentication plug-in to handle portal authentication. See <xref linkend="sect-CAS_Logout_Redirection"/> for details. The callback handler is enabled by default. Set the parameter to false if the Authentication Plugin on the CAS server side is not required. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.login.module.enabled</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.login.module.enabled</term> + <listitem> + <para> Specifies whether a pre-defined SSO login module declared in <filename> JPP_SERVER/standalone/configuration/standalone.xml</filename> is used for authentication. When the property is set to &quot;true&quot;, the SSODelegateLoginModule delegates work to another login module, as specified using the <property>gatein.sso.login.module.class</property> property. SSODelegateLoginModule will also resend all its options to its delegate. </para> - - <para> + <para> This parameter removes the need to manually change any login module configuration in the standalone.xml file, which simplifies platform configuration. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.login.module.class</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.login.module.class</term> + <listitem> + <para> Specifies the classname of the login module SSODelegateLoginModule will delegate to. This parameter will work only if gatein.sso.login.module.enabled is specified. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.server.url</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.server.url</term> + <listitem> + <para> Specifies the URL from which the CAS server is accessible. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.portal.url</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.portal.url</term> + <listitem> + <para> Specifies the URL from which the JBoss Portal Platform is accessible. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.filter.logout.class</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.class</term> + <listitem> + <para> Specifies the class of the logout filter. In the example above <code>org.gatein.sso.agent.filter.CASLogoutFilter</code> is the correct choice because this filter is able to redirect to the CAS server and perform logout on CAS side. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.filter.logout.url</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.url</term> + <listitem> + <para> Specifies the CAS server logout URL, which is used for redirection by the logout filter </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.filter.logout.enabled</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.enabled</term> + <listitem> + <para> Optional parameter, which specifies whether the logout interceptor is enabled. To disable logout on CAS side, set the parameter value to &quot; false&quot; . This results in both options <code>gatein.sso.filter.logout.class</code> and <code>gatein.sso.filter.logout.url</code> are ignored </para> - - <para> + <para> When a user logs out of the portal, the CAS authentication ticket is still valid for other CAS authenticated sites. </para> - </listitem> - </varlistentry> - - <varlistentry> - <term>gatein.sso.filter.login.sso.url</term> - - <listitem> - <para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.login.sso.url</term> + <listitem> + <para> Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page. </para> - <remark>Docs Note - jmorgan - added this note about the p.c.n variable, and that it *shouldn&apos;t* be substituted for a hard-coded variable name.</remark> - <note> - <para> + <remark>Docs Note - jmorgan - added this note about the p.c.n variable, and that it *shouldn&apos;t* be substituted for a hard-coded variable name.</remark> + <note> + <para> The string <literal&gt;@@portal.container.name(a)@ </literal>is dynamically replaced when the URL is interpreted by the platform&apos;s SSO Component. It is recommended that this string is used over hard-coding the name of the portal for future maintenance and ease of configuration changes. </para> - </note> - </listitem> - </varlistentry> - </variablelist> - </section> - </section> - - <section id="sect-Deploying_CAS_on_Tomcat"> - <title><remark>BZ#856430 </remark>Build and Deploy the CAS</title> - <remark>BZ#856430 - jmorgan - This is a new sections which captures the final step an admin needs to do to bring all the cofiguration together.</remark> - <para> + </note> + </listitem> + </varlistentry> + </variablelist> + </section> + </section> + <section id="sect-Deploying_CAS_on_Tomcat"> + <title><remark>BZ#856430 </remark>Build and Deploy the CAS</title> + <remark>BZ#856430 - jmorgan - This is a new sections which captures the final step an admin needs to do to bring all the cofiguration together.</remark> + <para> Jasig CAS uses Apache Maven to build the <filename>cas.war</filename> file. Follow the instructions to produce this file, and deploy it to the Apache Tomcat server. </para> - - <procedure> - <title>Building CAS, and Deploying to Tomcat</title> - - <step> - <para> + <procedure> + <title>Building CAS, and Deploying to Tomcat</title> + <step> + <para> Install Maven by following the recommendations and links in the <ulink url="https://wiki.jasig.org/display/CASUM/Building+and+Deploying&quo... and Deploying section</ulink> of the Jasig CAS user documentation. </para> - </step> - - <step> - <para> + </step> + <step> + <para> In a terminal, navigate to <filename>CAS_DIR/cas-server-webapp/</filename>, and run <command>mvn install</command>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Copy <filename>CAS_DIR/cas-server-webapp/target/cas.war</filename> to <filename>TOMCAT_HOME/webapps</filename>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Tomcat should be running by default, if the process has been followed up to this step. Start JBoss Portal Platform, and verify the server is running by opening <ulink url="http://localhost:8080/"/>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Open <ulink url="http://localhost:8888/cas"/> to verify the CAS server has correctly deployed to Tomcat. If the link does not open the CAS login page, restart Apache Tomcat and try again. </para> - </step> - </procedure> - <remark>BZ#856430 - jmorgan - Added this &quot;wrap up&quot; statement that should describe what customers are able to do after following the procedure.</remark> - <para> + </step> + </procedure> + <remark>BZ#856430 - jmorgan - Added this &quot;wrap up&quot; statement that should describe what customers are able to do after following the procedure.</remark> + <para> The CAS server is now deployed to Tomcat, and the portal will now redirect users to the CAS login page when they click on the Sign In link. </para> - </section> - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> - <title><remark>BZ#856430</remark>Java Open Single Sign-On Project</title> - - <para> + </section> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> + <title><remark>BZ#856430</remark>Java Open Single Sign-On Project</title> + <para> Configuring JOSSO for JBoss Enterprise Application Platform requires an Apache server instance to host JOSSO. JBoss Enterprise Application Platform communicates with the JOSSO Apache instance through the single sign-on plug-in. </para> - - <para> + <para> This single sign-on plug-in enables seamless integration between JBoss Portal Platform and the Java Open Single Sign-On (JOSSO) framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"/> . </para> - - <para> + <para> The procedures in this section detail setting up the JOSSO server to authenticate against the JBoss Portal Platform login module. </para> - - <para> + <para> After completing the procedures in this section, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. </para> - - <section> - <title>Authentication Process</title> - - <para> + <section> + <title>Authentication Process</title> + <para> The login workflow for JOSSO is quite similar to that used for CAS authentications (specific details can be found in <xref linkend="sect-CAS-Authentication_Process"/>). </para> - - <para> + <para> Briefly; when a user clicks to sign in to a portal they are redirected to the JOSSO login screen, where they supply the appropriate credentials. They are then redirected (with access authorization) back to the Portal. </para> - - <para> + <para> The <systemitem>JOSSOAgent</systemitem> component performs a validation of the authorization ticket with the JOSSO server via a back channel after the <systemitem>InitiateLoginFilter</systemitem> has delegated the <parameter>josso_assertion_id</parameter> request to it. The JOSSO agent and JOSSO server communicate via web services. </para> - - <para> + <para> After a successful validation, the user identity is successfully established and the user is logged into the requested Portal. </para> - - <para> + <para> On logout, <systemitem>JOSSOLogoutFilter</systemitem> performs a logout on both the Portal and the JOSSO server (similar to the process for CAS). </para> - - <para> + <para> While the authentication plugin (which is able to send REST requests to the portal, receive the response, and authenticate the user on the JOSSO side) is supported, this support is only for JOSSO 1.8 (not JOSSO 2.2 as at this release). </para> - - <para> + <para> In this section, we will assume that JBoss Portal Platform will be running on JBoss Enterprise Application Platform 6 using port <emphasis role="italics">localhost:8080</emphasis> and that the JOSSO server will be running on Tomcat, using <emphasis role="italics">localhost:8888</emphasis>. </para> - - <note> - <para> + <note> + <para> There are differences between various JOSSO minor versions (especially betweeen JOSSO versions 1.8.1 and 1.8.2) so instructions will be slightly different between various versions. This will be pointed in text in more details. </para> - </note> - </section> - - <section> - <title>JOSSO 1.8</title> - - <section id="sid-55477376_JOSSO-ObtainingJOSSO"> - <title>Obtaining JOSSO</title> - - <para> + </note> + </section> + <section> + <title>JOSSO 1.8</title> + <section id="sid-55477376_JOSSO-ObtainingJOSSO"> + <title>Obtaining JOSSO</title> + <para> JOSSO can be downloaded from <ulink url="http://sourceforge.net/projects/josso/files/"/>;. Use the package that embeds Apache Tomcat. </para> - <remark>Docs Note; JOSSO versions up to 1.8.7 are available from this URL. I assume any after 1.8.2 are unsupported. Should we call this out in the docs?</remark> - <para> + <remark>Docs Note; JOSSO versions up to 1.8.7 are available from this URL. I assume any after 1.8.2 are unsupported. Should we call this out in the docs?</remark> + <para> Once downloaded, extract the package into what will be called <replaceable>JOSSO_HOME</replaceable> in this example. </para> - </section> - - <section id="sid-55477376_JOSSO-JOSSOserver"> - <title>Set up the JOSSO server</title> - - <para> + </section> + <section id="sid-55477376_JOSSO-JOSSOserver"> + <title>Set up the JOSSO server</title> + <para> This section describes how to set up the JOSSO server to authenticate against the JBoss Portal Platform using the REST authentication plugin. In this example, the JOSSO server will be installed on Tomcat. </para> - - <procedure> - <step> - <para> + <procedure> + <step> + <para> <emphasis role="bold">Optional:</emphasis> To use the SSO authentication plugin with JOSSO (not-mandatory but recommended. See <xref linkend="sect-CAS-Authentication_Process"/> for details): </para> - <substeps> - <step><para> + <substeps> + <step> + <para> Copy the files from <filename>SSO_HOME/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/</filename> into <replaceable>JOSSO_HOME</replaceable> directory, as shown below: </para> - <para> + <para> Keep in mind that <replaceable>SSO_HOME</replaceable> refers to the JOSSO directory within JBoss Portal Platform as mentioned in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On"/>. </para> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> Copy <filename><replaceable>SSO_HOME</replaceable>/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/lib/josso-gateway-config.xml</filename> to <filename><replaceable>JOSSO_HOME</replaceable>/lib/josso-gateway-config.xml</filename>. The original file is being replaced. You should consider creating a backup of it before adding the new file. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Add <filename><replaceable>SSO_HOME</replaceable>/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/lib/josso-gateway-config.xml</filename> to <filename><replaceable>JOSSO_HOME</replaceable>/lib/</filename>. This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> Add <filename>SSO_HOME/josso/josso-<replaceable>&lt;version&gt;</replaceable>/plugin/webapps/josso/WEB-INF/classes/gatein.properties</filename> to <filename>JOSSO_HOME/webapps/josso/WEB-INF/classes/</filename>. This file is not present in the original <replaceable>JOSSO_HOME</replaceable> download. </para> - - <para> + <para> This file may need to be reconfigured according to your JBoss Portal Platform environment (you need to use the host and port of your JBoss Portal Platform instance as this will be used by the Authentication plugin to send REST requests over HTTP). </para> - </listitem> - </itemizedlist> - </step> - </substeps> - </step> - - <step> - <para> + </listitem> + </itemizedlist> + </step> + </substeps> + </step> + <step> + <para> Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and replace the <literal>8080</literal> port to <literal>8888</literal> to change the default Tomcat port and avoid a conflict with the default JBoss Portal Platform port (for testing purposes). </para> - - <note> - <title>Port Conflicts</title> - - <para> + <note> + <title>Port Conflicts</title> + <para> If JBoss Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to <literal>8080</literal> to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from <literal>8005</literal> to <literal>8805</literal>, and AJP port from <literal>8009</literal> to <literal>8809</literal>. </para> - </note> - </step> - - <step> - <para> + </note> + </step> + <step> + <para> Tomcat should now allow access to <uri>http://localhost:8888/josso/signon/login.do</uri>. However, if you are using the SSO Authentication plugin, the login will not be available as you must set up your JBoss Portal Platform instance to use it. </para> - - <figure> - <title>JOSSO Login Page</title> - <mediaobject> - <imageobject role="html"> - <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/josso.png" format="PNG"/> - </imageobject> - </mediaobject> - </figure> - </step> - </procedure> - </section> - - <section id="sid-55477376_JOSSO-SetuptheJOSSOclient"> - <title>Set up the JOSSO client</title> - - <procedure> - <step> - <para> + <figure> + <title>JOSSO Login Page</title> + <mediaobject> + <imageobject role="html"> + <imagedata align="center" fileref="images/AuthenticationAndIdentity/SSO/josso.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + </step> + </procedure> + </section> + <section id="sid-55477376_JOSSO-SetuptheJOSSOclient"> + <title>Set up the JOSSO client</title> + <procedure> + <step> + <para> Some of the configuration properties in <filename>JBOSS_HOME/standalone/configuration/gatein/configuration.properties</filename> need to be set on the client server. </para> - - <para> + <para> Locate the <literal>#SSO</literal> section of the file and edit it to match the sample below: </para> - - <informalexample> -<programlisting> + <informalexample> + <programlisting> #SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} @@ -861,284 +702,230 @@ gatein.sso.filter.logout.url=${gatein.sso.josso.base.url}/logout.do gatein.sso.filter.login.sso.url=${gatein.sso.server.url}?josso_back_to=${gatein.sso.portal.url}/@@portal.container.name@(a)/initiatessologin </programlisting> - </informalexample> - - <para> + </informalexample> + <para> Most of the properties are described in <xref linkend="sect-CAS_Configuring_the_Platform"/>. </para> - - <para> + <para> Some of the properites differ for JOSSO: </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> The Logout filter is <code>org.gatein.sso.agent.filter.JOSSOLogoutFilter</code>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> <code>gatein.sso.josso.host</code> points to the location of the JOSSO server. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> <code>gatein.sso.portal.url</code> must be changed if you intend to access JBoss Portal Platform on any URL other than <emphasis role="italics">localhost:8080</emphasis>. </para> - </listitem> - - <listitem> - <para> + </listitem> + <listitem> + <para> The <code>gatein.sso.josso.agent.config.file</code> property points to the location of the Agent configuration file, which is relative to classpath. Therefore the agent file location is actually located at <filename>JBOSS_HOME/gatein/gatein.ear/portal.war/WEB-INF/classes/sso/josso/1.8/josso-agent-config.xml</filename>. </para> - - <para> + <para> In the majority of cases, nothing in this file will need to be configured beyond the defaults. </para> - </listitem> - </itemizedlist> - </step> - - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> JOSSO has some specific dependencies, which differ between various versions. The original <code>org.gatein.sso</code> SSO module must be replaced with one appropriate for your version of JOSSO. The alternate modules are available in the JOSSO download. </para> - - <substeps> - <step> - <para> + <substeps> + <step> + <para> Delete the <filename>JBOSS_HOME/modules/org/gatein/sso</filename> directory. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Copy the <filename>SSO_HOME/josso/gatein-josso-<replaceable>&lt;version&gt;</replaceable>/modules/org/gatein/sso</filename> directory into <filename>JBOSS_HOME/modules/org/gatein/</filename>. </para> - </step> - </substeps> - </step> - </procedure> - - <para> + </step> + </substeps> + </step> + </procedure> + <para> From now on, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. If you set Authentication plugin for JOSSO, you can login with JBoss Portal Platform credentials (like john/gtn) on JOSSO side. </para> - </section> - </section> - - <section> - <title>JOSSO 2.2</title> - - <para> + </section> + </section> + <section> + <title>JOSSO 2.2</title> + <para> JOSSO 2.2 takes a different approach to SSO than JOSSO 1.8. It is designed to allow users to create their own SSO environment by modelling it in a flash web application called <emphasis role="strong">atricore-console</emphasis>. </para> - - <para> + <para> Unfortunately this make it more difficult to use the SSO Authentication plugin as it is not easily possible to configure an existing JOSSO 2.2 environment via Spring XML files. Using the <systemitem>AuthenticationPlugin</systemitem> with JOSSO 2.2 is not supported. </para> - - <section id="sid-55477376_JOSSO-JOSSO2.2serversetup"> - <title>JOSSO 2.2 server setup</title> - - <para> + <section id="sid-55477376_JOSSO-JOSSO2.2serversetup"> + <title>JOSSO 2.2 server setup</title> + <para> You can downloaded JOSSO 2.2.0 from <ulink url="http://www.josso.org">JOSSO site</ulink> and follow the instructions from the JOSSO 2 quickstart in <ulink url="http://www.josso.org/confluence/display/JOSSO1/JOSSO2+Quick+sta... . </para> - - <para> + <para> After unzipping the download and running the JOSSO, you can access the <application>atricore</application> console at <uri>http://<replaceable>server.local.network</replaceable>:8081/atricore-console</uri> (<replaceable>server.local.network</replaceable> is the virtual host defined in <filename>/etc/hosts</filename>). </para> - - <procedure> - <step> - <para> + <procedure> + <step> + <para> Login to the portal with the username/password combination; <literal>admin/admin</literal>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Create a new, empty <emphasis role="italics">Identity appliance</emphasis> with the following details: </para> - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - Setting - </entry> - <entry> - Value - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - Name - </entry> - <entry> - <parameter>MYFIRSTIA</parameter> - </entry> - </row> - <row> - <entry> - Realm name - </entry> - <entry> - <parameter>com.mycompany.myrealm</parameter> - </entry> - </row> - <row> - <entry> - Appliance location - </entry> - <entry> - <uri>http://server.local.network:8081</uri> - </entry> - </row> - </tbody> - </tgroup> - </table> - </step> - - <step> - <para> + <table> + <title/> + <tgroup cols="2"> + <thead> + <row> + <entry> Setting </entry> + <entry> Value </entry> + </row> + </thead> + <tbody> + <row> + <entry> Name </entry> + <entry> + <parameter>MYFIRSTIA</parameter> + </entry> + </row> + <row> + <entry> Realm name </entry> + <entry> + <parameter>com.mycompany.myrealm</parameter> + </entry> + </row> + <row> + <entry> Appliance location </entry> + <entry> + <uri>http://server.local.network:8081</uri> + </entry> + </row> + </tbody> + </tgroup> + </table> + </step> + <step> + <para> Create a new Identity provider named <emphasis role="italics">AcmeIDP</emphasis> (use the default settings). - </para> - </step> - - <step> - <para> + </para> + </step> + <step> + <para> Create an Identity vault <emphasis role="italics">IDPUsers</emphasis> and connect it with <emphasis role="italics">AcmeIDP</emphasis> via <emphasis role="italics">Identity lookup</emphasis> connection. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Create a Service provider called <emphasis role="italics">SP1</emphasis> but let the hosts to be on <emphasis role="italics">server.local.network:8081</emphasis>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Create an Identity vault <emphasis role="italics">SP1Users</emphasis> and wire it with SP1 via <emphasis role="italics">Identity lookup</emphasis> connection. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Create empty temporary directory <filename>/tmp/tomcat7</filename> and then in the <application>atricore</application> console create new Execution environment of type <emphasis role="italics">Tomcat</emphasis> with the following parameters: </para> - <table> - <title></title> - <tgroup cols="2"> - <thead> - <row> - <entry> - Setting - </entry> - <entry> - Value - </entry> - </row> - </thead> - <tbody> - <row> - <entry> - Name - </entry> - <entry> - <parameter>SP1EE</parameter> - </entry> - </row> - <row> - <entry> - Version - </entry> - <entry> - <parameter>7.0.x</parameter> - </entry> - </row> - <row> - <entry> - Target host - </entry> - <entry> - <parameter>Local</parameter> - </entry> - </row> - <row> - <entry> - Install home - </entry> - <entry> - <parameter>/tmp/tomcat7</parameter> (the <code>/tmp/tomcat7</code> directory must exist, but it can be empty). - </entry> - </row> - </tbody> - </tgroup> - </table> - </step> - - <step> - <para> + <table> + <title/> + <tgroup cols="2"> + <thead> + <row> + <entry> Setting </entry> + <entry> Value </entry> + </row> + </thead> + <tbody> + <row> + <entry> Name </entry> + <entry> + <parameter>SP1EE</parameter> + </entry> + </row> + <row> + <entry> Version </entry> + <entry> + <parameter>7.0.x</parameter> + </entry> + </row> + <row> + <entry> Target host </entry> + <entry> + <parameter>Local</parameter> + </entry> + </row> + <row> + <entry> Install home </entry> + <entry><parameter>/tmp/tomcat7</parameter> (the <code>/tmp/tomcat7</code> directory must exist, but it can be empty). </entry> + </row> + </tbody> + </tgroup> + </table> + </step> + <step> + <para> Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">SP1EE</emphasis> via an <emphasis role="italics">Activation</emphasis> connection. </para> - - <para> - <remark>Docs note: I don't even know what this sentence is trying to say.</remark> Left default values of parameters instead of parameter <emphasis role="italics">Partner application location</emphasis> needs to be configured to <ulink url="http://localhost:8080/portal"/> + <para> + <remark>Docs note: I don&apos;t even know what this sentence is trying to say.</remark> Left default values of parameters instead of parameter <emphasis role="italics">Partner application location</emphasis> needs to be configured to <ulink url="http://localhost:8080/portal"/> </para> - </step> - - <step> - <para> + </step> + <step> + <para> Wire <emphasis role="italics">SP1</emphasis> and <emphasis role="italics">AcmeIDP</emphasis> via <emphasis role="italics">Federated connection</emphasis>. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Click <guilabel>Save</guilabel> and save this model. </para> - </step> - - <step> - <para> - Go to the <guilabel>Identity appliance lifecycle management</guilabel> tab and go through lifecycle of Identity appliance (<menuchoice><guimenuitem>Saved</guimenuitem><guimenuitem>Staged</guimenuitem><guimenuitem>Deployed</guimenuitem><guimenuitem>Started</guimenuitem></menuchoice>) as suggested in the quickstart. + </step> + <step> + <para> + Go to the <guilabel>Identity appliance lifecycle management</guilabel> tab and go through lifecycle of Identity appliance (<menuchoice> + <guimenuitem>Saved</guimenuitem> + <guimenuitem>Staged</guimenuitem> + <guimenuitem>Deployed</guimenuitem> + <guimenuitem>Started</guimenuitem> + </menuchoice>) as suggested in the quickstart. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Go to the <guilabel>Account &amp; Entitlement management</guilabel> tab and create users. Users must be created this way because REST callbacks to the Portal are not supported in this release. </para> - - <para> + <para> This example will create the following user/password accounts: <literal>john</literal>/<literal>password</literal>, <literal>root</literal>/<literal>password</literal> and <literal>demo</literal>/<literal>password</literal>. </para> - </step> - </procedure> - </section> - - <section id="sid-55477376_JOSSO-JOSSOclientsetup"> - <title>JOSSO client setup</title> - - <para> + </step> + </procedure> + </section> + <section id="sid-55477376_JOSSO-JOSSOclientsetup"> + <title>JOSSO client setup</title> + <para> This section assumes that all relevant configurations were made as described in <xref linkend="sid-55477376_JOSSO-JOSSO2.2serversetup"/>. </para> - - <procedure> - <step> - <para> + <procedure> + <step> + <para> Assuming again that you have JBoss Portal Platform running on JBoss Enterprise Platform 6, you need to change some of the properties in the SSO sections of <filename>JBOSS_HOME/standalone/configuration/gatein/configuration.properties</filename> to match those below: </para> - - <informalexample> -<programlisting> + <informalexample> + <programlisting> # SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} @@ -1158,192 +945,177 @@ gatein.sso.josso.partnerAppPoint=SP1EE gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/IDBUS/${gatein.sso.josso.identityApplianceId}/${gatein.sso.josso.partnerAppPoint}/JOSSO/SSO/REDIR?josso_back_to=${gatein.sso.portal.url}/@@portal.container.name@(a)/josso_security_check&amp;amp;josso_partnerapp_id=${gatein.sso.josso.partnerAppId} </programlisting> - </informalexample> - - <para> + </informalexample> + <para> Note that <code>gatein.sso.filter.logout.url</code> is empty now as the logout URL will be obtained from the JOSSO agent configuration set in file <filename>JBOSS_HOME/gatein/gatein.ear/portal.war/WEB-INF/classes/sso/josso/2.2/josso-agent-config.xml</filename>. </para> - </step> - - <step> - <para> - Update the SSO module in EAP 6: + </step> + <step> + <para> + Update the SSO module in JBoss Enterprise Application Platform 6: </para> - - <substeps> - <step> - <para> + <substeps> + <step> + <para> Delete the <filename>JBOSS_HOME/modules/org/gatein/sso</filename> directory. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Copy the <filename>SSO_HOME/josso/gatein-josso-182/modules/org/gatein/sso</filename> into <filename>JBOSS_HOME/modules/org/gatein/</filename> directory. </para> - </step> - </substeps> - </step> - - <step> - <substeps> - <step> - <para> + </step> + </substeps> + </step> + <step> + <substeps> + <step> + <para> Start the Portal. </para> - - <para> + <para> Access <uri>http://localhost:8080/portal</uri> and click <emphasis role="italics">Sign in</emphasis>. </para> - - <para> + <para> You will be redirected to the JOSSO instance, but you will need to login with the username/password account created via the JOSSO console (for example <literal>john</literal>/<literal>password</literal>) as REST callbacks are not supported. </para> - - <para> + <para> After a successful login to JOSSO, you will be redirected to the Portal as <literal>john</literal>. </para> - </step> - </substeps> - </step> - </procedure> - </section> - </section> - - <section> - <title>Setup with portal on Tomcat</title> - - <para> + </step> + </substeps> + </step> + </procedure> + </section> + </section> + <section> + <title>Setup with portal on Tomcat</title> + <para> If you have JBoss Portal Platform on Tomcat 7 and you want to configure it for SSO against JOSSO you must complete the following additional steps: </para> - - <procedure> - <title></title> - - <step> - <para> + <procedure> + <title/> + <step> + <para> Add <code>ServletAccessValve</code> into <filename>server.xml</filename> (as was done to set up CAS single sign-on). Refer to <xref linkend="sect-Deploying_CAS_on_Tomcat"/> for more details. </para> - - </step> - - <step> - <para> + </step> + <step> + <para> Copy the JAR files for the appropriate JOSSO version from <filename>GATEIN_SSO_HOME/josso/gatein-josso-<replaceable>&lt;version&gt;</replaceable>/modules/org/gatein/sso/main into JBOSS_HOME/lib/</filename>. </para> - <para> + <para> Use <replaceable>gatein-josso-181</replaceable> if you are on JOSSO 1.8.1 or older or <replaceable>gatein-josso-182</replaceable> if you are on JOSSO 1.8.2 or newer or on JOSSO 2.2. </para> - </step> - </procedure> - </section> - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM"> - <title>OpenAM</title> - <para> - OpenAM is an open source access management, entitlements and federation server platform. It is a successor of OpenSSO, the access management and federation server platform whose integration was available in JBoss Enterprise Portal Platform 5. As the development of OpenSSO has been discontinued, the OpenSSO integration has been replaced with OpenAM integration in JBoss Portal Platform 6. - </para> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Login-Workflow"> - <title>Login and Logout Workflow</title> - <para> - When the OpenAM integration is configured and a user clicks the <guibutton>Sign in</guibutton> link on a JBoss Portal Platform page, they are redirected to the OpenAM login screen, where they provide their login credentials. Authentication on the OpenAM server side is performed by the JBoss Portal Platform SSO Authentication Plugin. The plugin sends a REST request to JBoss Portal Platform, obtains a response, and authenticates the user on the OpenAM side based on the response. - </para> - <para> - After successful authentication with OpenAM, an OpenAM authentication ticket is stored in the <systemitem>iPlanetDirectoryPro</systemitem> cookie in the client browser and the user is redirected back to the portal page. When the portal page is requested, the <systemitem>InitiateLoginFilter</systemitem> iterceptor delegates validation of the OpenAM ticket to the <systemitem>OpenSSOAgent</systemitem> component. The <systemitem>OpenSSOAgent</systemitem> then uses the OpenAM REST API to perform back channel validation of the ticket with the OpenAM server. After successful validation, user identity is established and the user is logged in to JBoss Portal Platform. - </para> - <para> - When logout is requested by clicking the <guibutton>Sign out</guibutton> button on a portal page, the <emphasis role="italics">OpenSSOLogoutFilter</emphasis> interceptor performs logout on both JBoss Portal Platform and the OpenAM server. - </para> - <para> - The OpenAM login and logout workflow is similar to the workflow that users go through with CAS, so you can refer to <xref linkend="sect-CAS-Authentication_Process"/> for more detailed information. - </para> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ObtainingOpenAM"> - <title>Obtaining OpenAM</title> - <para> - OpenAM must be obtained from <ulink url="http://forgerock.org/openam.html">Forgerock</ulink>;. Only the 9.5 and 10.0 versions of OpenAM are fully tested and supported with JBoss Portal Platform 6. Integration with other versions&#8212;including <ulink url="http://www.oracle.com/technetwork/testcontent/opensso-091890.ht...;, the predecessor of OpenAM&#8212;may be functional, but has not been fully tested and is therefore not supported. - </para> - <para> - The procedures in this section assume that OpenAM is obtained in the form of a ZIP distribution. Once downloaded, extract the contents of the ZIP package into a location of your choice. This location will be referred to as <code>OPENAM_HOME</code> in the following text. - </para> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-OpenAMserversetup"> - <title>OpenAM Server Setup</title> - <para> - This section contains procedures that need to be followed to set up an OpenAM server for authentication against JBoss Portal Platform. The authentication set up by these procedures is ensured by the JBoss Portal Platform SSO Authentication Plugin. The plugin will be installed in OpenAM and configured to perform authentication against the portal using a REST callback. - <note> - <para> - Using the REST callback as presented in this section is not mandatory. You can achieve authentication on the OpenAM side by any other means according to your preference. - </para> - </note> - </para> - <para> - To achieve the setup, perform the procedures in the following order: - <itemizedlist> - <listitem> - <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ModifyingtheOpenAMserver" /></para> - </listitem> - <listitem> - <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Authenticationpluginsetup" /></para> - </listitem> - <listitem> - <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI" /></para> - </listitem> - </itemizedlist> - </para> - <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ModifyingtheOpenAMserver"> - <title>Deploying the OpenAM Server</title> - <step> - <para> - Obtain a copy of Tomcat 7 and extract it into a suitable location. This location will be referred to as <code>TOMCAT_HOME</code> further in the text. - </para> - </step> - <step> - <para> - Deploy OpenAM to Tomcat by copying the <code>OPENAM_HOME/opensso/deployable-war/opensso.war</code> archive to the <code>TOMCAT_HOME/webapps/</code> directory. - </para> - <note> - <para> - The name of the WAR file is still <filename>opensso.war</filename>, even if it contains OpenAM, which is the successor of OpenSSO. The context of the OpenAM web application has also kept the name <code>/opensso</code>. - </para> - </note> - </step> - <step> - <para> - Change the default Tomcat port to avoid conflict with the default JBoss Portal Platform port. For the purpose of this example, let's change it to <literal>8888</literal> by editing the <code>TOMCAT_HOME/conf/server.xml</code> configuration file and replacing the <literal>8080</literal> port number with <literal>8888</literal>. - </para> - </step> - <step performance="optional"> - <para> - If JBoss Portal Platform is running on the same machine as Tomcat, other Tomcat port numbers also need to be changed to avoid conflicts. These port numbers can be changed to any unassigned port numbers available on the machine. For example, you can change the admin port from <literal>8005</literal> to <literal>8805</literal> and the AJP port from <literal>8009</literal> to <literal>8809</literal> if the latter are not assigned. - </para> - </step> - </procedure> - <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Authenticationpluginsetup"> - <title>Adding the Authentication Plug-in</title> - <step> - <para> - Copy the contents of the <code>JPP_DIST/gatein-sso/opensso/plugin/</code> directory to <code>TOMCAT_HOME/webapps/opensso/</code>. This will add: - </para> - <itemizedlist> - <listitem> - <para> - the <filename>AuthenticationPlugin.xml</filename> file to the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/</filename> directory. The file contains the following configuration: - </para> - <informalexample> -<programlisting language="XML"> -&lt;?xml version='1.0' encoding="UTF-8"?&gt; -&lt;!DOCTYPE ModuleProperties PUBLIC "=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN" "jar://com/sun/identity/authentication/Auth_Module_Properties.dtd"&gt; - -&lt;ModuleProperties moduleName="AuthenticationPlugin" version="1.0"&gt; - &lt;Callbacks length="2" order="1" timeout="60" header="GateIn OpenAM Login"&gt; + </step> + </procedure> + </section> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM"> + <title>OpenAM</title> + <para> + OpenAM is an open source access management, entitlements and federation server platform. It is a successor of OpenSSO, the access management and federation server platform whose integration was available in JBoss Enterprise Portal Platform 5. As the development of OpenSSO has been discontinued, the OpenSSO integration has been replaced with OpenAM integration in JBoss Portal Platform 6. + </para> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Login-Workflow"> + <title>Login and Logout Workflow</title> + <para> + When the OpenAM integration is configured and a user clicks the <guibutton>Sign in</guibutton> link on a JBoss Portal Platform page, they are redirected to the OpenAM login screen, where they provide their login credentials. Authentication on the OpenAM server side is performed by the JBoss Portal Platform SSO Authentication Plugin. The plugin sends a REST request to JBoss Portal Platform, obtains a response, and authenticates the user on the OpenAM side based on the response. + </para> + <para> + After successful authentication with OpenAM, an OpenAM authentication ticket is stored in the <systemitem>iPlanetDirectoryPro</systemitem> cookie in the client browser and the user is redirected back to the portal page. When the portal page is requested, the <systemitem>InitiateLoginFilter</systemitem> iterceptor delegates validation of the OpenAM ticket to the <systemitem>OpenSSOAgent</systemitem> component. The <systemitem>OpenSSOAgent</systemitem> then uses the OpenAM REST API to perform back channel validation of the ticket with the OpenAM server. After successful validation, user identity is established and the user is logged in to JBoss Portal Platform. + </para> + <para> + When logout is requested by clicking the <guibutton>Sign out</guibutton> button on a portal page, the <emphasis role="italics">OpenSSOLogoutFilter</emphasis> interceptor performs logout on both JBoss Portal Platform and the OpenAM server. + </para> + <para> + The OpenAM login and logout workflow is similar to the workflow that users go through with CAS, so you can refer to <xref linkend="sect-CAS-Authentication_Process"/> for more detailed information. + </para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ObtainingOpenAM"> + <title>Obtaining OpenAM</title> + <para> + OpenAM must be obtained from <ulink url="http://forgerock.org/openam.html">Forgerock</ulink>;. Only the 9.5 and 10.0 versions of OpenAM are fully tested and supported with JBoss Portal Platform 6. Integration with other versions—including <ulink url="http://www.oracle.com/technetwork/testcontent/opensso-091890.ht...;, the predecessor of OpenAM—may be functional, but has not been fully tested and is therefore not supported. + </para> + <para> + The procedures in this section assume that OpenAM is obtained in the form of a ZIP distribution. Once downloaded, extract the contents of the ZIP package into a location of your choice. This location will be referred to as <code>OPENAM_HOME</code> in the following text. + </para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-OpenAMserversetup"> + <title>OpenAM Server Setup</title> + <para> + This section contains procedures that need to be followed to set up an OpenAM server for authentication against JBoss Portal Platform. The authentication set up by these procedures is ensured by the JBoss Portal Platform SSO Authentication Plugin. The plugin will be installed in OpenAM and configured to perform authentication against the portal using a REST callback. + <note> + <para> + Using the REST callback as presented in this section is not mandatory. You can achieve authentication on the OpenAM side by any other means according to your preference. + </para> + </note> + </para> + <para> + To achieve the setup, perform the procedures in the following order: + <itemizedlist> + <listitem> + <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ModifyingtheOpenAMserver"/></para> + </listitem> + <listitem> + <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Authenticationpluginsetup"/></para> + </listitem> + <listitem> + <para><xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI"/></para> + </listitem> + </itemizedlist> + </para> + <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ModifyingtheOpenAMserver"> + <title>Deploying the OpenAM Server</title> + <step> + <para> + Obtain a copy of Tomcat 7 and extract it into a suitable location. This location will be referred to as <code>TOMCAT_HOME</code> further in the text. + </para> + </step> + <step> + <para> + Deploy OpenAM to Tomcat by copying the <code>OPENAM_HOME/opensso/deployable-war/opensso.war</code> archive to the <code>TOMCAT_HOME/webapps/</code> directory. + </para> + <note> + <para> + The name of the WAR file is still <filename>opensso.war</filename>, even if it contains OpenAM, which is the successor of OpenSSO. The context of the OpenAM web application has also kept the name <code>/opensso</code>. + </para> + </note> + </step> + <step> + <para> + Change the default Tomcat port to avoid conflict with the default JBoss Portal Platform port. For the purpose of this example, let&apos;s change it to <literal>8888</literal> by editing the <code>TOMCAT_HOME/conf/server.xml</code> configuration file and replacing the <literal>8080</literal> port number with <literal>8888</literal>. + </para> + </step> + <step performance="optional"> + <para> + If JBoss Portal Platform is running on the same machine as Tomcat, other Tomcat port numbers also need to be changed to avoid conflicts. These port numbers can be changed to any unassigned port numbers available on the machine. For example, you can change the admin port from <literal>8005</literal> to <literal>8805</literal> and the AJP port from <literal>8009</literal> to <literal>8809</literal> if the latter are not assigned. + </para> + </step> + </procedure> + <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Authenticationpluginsetup"> + <title>Adding the Authentication Plug-in</title> + <step> + <para> + Copy the contents of the <code>JPP_DIST/gatein-sso/opensso/plugin/</code> directory to <code>TOMCAT_HOME/webapps/opensso/</code>. This will add: + </para> + <itemizedlist> + <listitem> + <para> + the <filename>AuthenticationPlugin.xml</filename> file to the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/</filename> directory. The file contains the following configuration: + </para> + <informalexample> + <programlisting language="XML"> +&lt;?xml version=&apos;1.0&apos; encoding=&quot;UTF-8&quot;?&gt; +&lt;!DOCTYPE ModuleProperties PUBLIC &quot;=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN&quot; &quot;jar://com/sun/identity/authentication/Auth_Module_Properties.dtd&quot;&gt; + +&lt;ModuleProperties moduleName=&quot;AuthenticationPlugin&quot; version=&quot;1.0&quot;&gt; + &lt;Callbacks length=&quot;2&quot; order=&quot;1&quot; timeout=&quot;60&quot; header=&quot;GateIn OpenAM Login&quot;&gt; &lt;NameCallback&gt; &lt;Prompt&gt; Username &lt;/Prompt&gt; &lt;/NameCallback&gt; - &lt;PasswordCallback echoPassword="false"&gt; + &lt;PasswordCallback echoPassword=&quot;false&quot;&gt; &lt;Prompt&gt; Password &lt;/Prompt&gt; @@ -1351,94 +1123,102 @@ &lt;/Callbacks&gt; &lt;/ModuleProperties&gt; </programlisting> - </informalexample> - </listitem> - <listitem> - <para> - the <filename>sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> and <filename>commons-httpclient-&lt;VERSION&gt;.jar</filename> archives to the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename> directory. - </para> - </listitem> - <listitem> - <para> - the <filename>gatein.properties</filename> file to the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes/</filename> directory. You may need to change the values specified in this file to match the configuration of the JBoss Portal Platform instance. The values will be used by the authentication plugin to establish the REST connection to the portal. - </para> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Start Tomcat and verify that you are able to access the OpenAM user interface at <ulink url="http://localhost:8888/opensso"/>. - </para> - </step> - </procedure> - <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI"> - <title>Configuring a Realm in OpenAM User Interface</title> - <step> - <para> - Direct your browser to <ulink url="http://localhost:8888/opensso"/>. - </para> - </step> - <step> - <para>Create the default configuration.</para> - </step> - <step> - <para> - Login as <systemitem class="username">amadmin</systemitem> and navigate to <menuchoice><guimenu>Configuration</guimenu><guimenuitem>Authentication</guimenuitem></menuchoice>. - </para> - </step> - <step> - <para> - Select the <guibutton>Core</guibutton> link, add a new value containing the <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal> class name and click <guibutton>Save</guibutton>. This step is important for the JBoss Portal Platform SSO Authentication Plugin to be available among other OpenAM authentication modules. - </para> - </step> - <step> - <para> - Go to the <guimenu>Access control</guimenu> tab and create a new realm called <literal>gatein</literal>. - </para> - </step> - <step> - <para> - Go to the <literal>gatein</literal> realm and click the <guimenu>Authentication</guimenu> tab. In the <guimenu>Authentication chaining</guimenu> section at the bottom of the tab, click <guibutton>ldapService</guibutton>. Here, change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. This ensures that authentication of the <literal>gatein</literal> realm will be performed using the JBoss Portal Platform REST service instead of the OpenAM LDAP server. - </para> - </step> - <step> - <para> - Still on the <guimenu>Authentication</guimenu> tab of the <literal>gatein</literal> realm, click the <guibutton>All Core Settings</guibutton> button. When the settings are displayed, change the <guilabel>UserProfile</guilabel> value from <literal>Required</literal> to <literal>Dynamic</literal>. This is needed because JBoss Portal Platform users are not initially present in the OpenAM LDAP server datastore. The <literal>Dynamic</literal> value ensures that all users are automatically added the datastore after their first successful authentication. - </para> - </step> - <step> - <para> - Go to <menuchoice><guimenu>Access control</guimenu><guimenuitem>Top level realm</guimenuitem><guimenuitem>Privileges</guimenuitem><guimenuitem>All authenticated users</guimenuitem></menuchoice> and check the following checkboxes: - </para> - <itemizedlist> - <listitem> - <para> - <guilabel>Read and write access only for policy properties</guilabel> - </para> - </listitem> - <listitem> - <para> - <guilabel>Read and write access to all realm and policy properties</guilabel> - </para> - </listitem> - </itemizedlist> - <para> - Adding these privileges allows REST access to the OpenAM server. - </para> - </step> - <step> - <para> - Repeat the previous step to increase the privileges also for the <literal>gatein</literal> realm. - </para> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-SetuptheOpenAMclient"> - <title>JBoss Portal Platform Setup as OpenAM Client</title> - <para> - On the JBoss Portal Platform server, you need to ensure proper configuration of single sign-on properties in the <code>JPP_SERVER/standalone/configuration/gatein/configuration.properties</code> file. Locate the SSO section in this file and change/add properties in the section as follows: - </para> -<programlisting># SSO + </informalexample> + </listitem> + <listitem> + <para> + the <filename>sso-opensso-plugin-&lt;VERSION&gt;.jar</filename> and <filename>commons-httpclient-&lt;VERSION&gt;.jar</filename> archives to the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename> directory. + </para> + </listitem> + <listitem> + <para> + the <filename>gatein.properties</filename> file to the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes/</filename> directory. You may need to change the values specified in this file to match the configuration of the JBoss Portal Platform instance. The values will be used by the authentication plugin to establish the REST connection to the portal. + </para> + </listitem> + </itemizedlist> + </step> + <step> + <para> + Start Tomcat and verify that you are able to access the OpenAM user interface at <ulink url="http://localhost:8888/opensso"/>. + </para> + </step> + </procedure> + <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI"> + <title>Configuring a Realm in OpenAM User Interface</title> + <step> + <para> + Direct your browser to <ulink url="http://localhost:8888/opensso"/>. + </para> + </step> + <step> + <para>Create the default configuration.</para> + </step> + <step> + <para> + Login as <systemitem class="username">amadmin</systemitem> and navigate to <menuchoice> + <guimenu>Configuration</guimenu> + <guimenuitem>Authentication</guimenuitem> + </menuchoice>. + </para> + </step> + <step> + <para> + Select the <guibutton>Core</guibutton> link, add a new value containing the <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal> class name and click <guibutton>Save</guibutton>. This step is important for the JBoss Portal Platform SSO Authentication Plugin to be available among other OpenAM authentication modules. + </para> + </step> + <step> + <para> + Go to the <guimenu>Access control</guimenu> tab and create a new realm called <literal>gatein</literal>. + </para> + </step> + <step> + <para> + Go to the <literal>gatein</literal> realm and click the <guimenu>Authentication</guimenu> tab. In the <guimenu>Authentication chaining</guimenu> section at the bottom of the tab, click <guibutton>ldapService</guibutton>. Here, change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. This ensures that authentication of the <literal>gatein</literal> realm will be performed using the JBoss Portal Platform REST service instead of the OpenAM LDAP server. + </para> + </step> + <step> + <para> + Still on the <guimenu>Authentication</guimenu> tab of the <literal>gatein</literal> realm, click the <guibutton>All Core Settings</guibutton> button. When the settings are displayed, change the <guilabel>UserProfile</guilabel> value from <literal>Required</literal> to <literal>Dynamic</literal>. This is needed because JBoss Portal Platform users are not initially present in the OpenAM LDAP server datastore. The <literal>Dynamic</literal> value ensures that all users are automatically added the datastore after their first successful authentication. + </para> + </step> + <step> + <para> + Go to <menuchoice> + <guimenu>Access control</guimenu> + <guimenuitem>Top level realm</guimenuitem> + <guimenuitem>Privileges</guimenuitem> + <guimenuitem>All authenticated users</guimenuitem> + </menuchoice> and check the following checkboxes: + </para> + <itemizedlist> + <listitem> + <para> + <guilabel>Read and write access only for policy properties</guilabel> + </para> + </listitem> + <listitem> + <para> + <guilabel>Read and write access to all realm and policy properties</guilabel> + </para> + </listitem> + </itemizedlist> + <para> + Adding these privileges allows REST access to the OpenAM server. + </para> + </step> + <step> + <para> + Repeat the previous step to increase the privileges also for the <literal>gatein</literal> realm. + </para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-SetuptheOpenAMclient"> + <title>JBoss Portal Platform Setup as OpenAM Client</title> + <para> + On the JBoss Portal Platform server, you need to ensure proper configuration of single sign-on properties in the <code>JPP_SERVER/standalone/configuration/gatein/configuration.properties</code> file. Locate the SSO section in this file and change/add properties in the section as follows: + </para> + <programlisting># SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} gatein.sso.login.module.enabled=${gatein.sso.enabled} @@ -1450,59 +1230,59 @@ gatein.sso.filter.logout.url=${gatein.sso.server.url}/UI/Logout gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/UI/Login?realm=${gatein.sso.openam.realm}&amp;amp;goto=${gatein.sso.portal.url}/@@portal.container.name@(a)/initiatessologin </programlisting> - <para> - Most of the properties are already described for CAS integration in <xref linkend="sect-CAS_Configuring_the_Platform" />, so you can refer to that section for detailed information. - </para> - <para> - Values of some properties are different with OpenAM, specifically the URLs for login/logout redirection, the logout filter class and the <code>gatein.sso.server.url</code> property, which points to the location of the OpenAM server. The <code>gatein.sso.openam.realm</code> value points to the realm created on the OpenAM server in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI" />. - </para> - <para> - With all the previously described configuration, all links redirecting users to authentication pages will redirect them to the OpenAM authentication form. On the OpenAM side, users will be able to log in to the <literal>gatein</literal> realm using their JBoss Portal Platform credentials. - </para> - <para> - <figure> - <title>OpenAM Login Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/AuthenticationAndIdentity/SSO/openam.png"/> - </imageobject> - </mediaobject> - </figure> - </para> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-CrossdomainauthenticationwithOpenAM"> - <title>Cross-domain Authentication with OpenAM</title> - <para> - The configuration described in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-OpenAMserversetup" /> and <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-SetuptheOpenAMclient" /> assumes that JBoss Portal Platform and OpenAM are deployed on the same server or in the same DNS domain. - </para> - <para> - In such an environment, OpenAM adds the <systemitem>iPlanetDirectoryPro</systemitem> cookie for the shared domain to the client browser. It stores the authentiction token in the cookie and performs redirection to the <systemitem>OpenSSOAgent</systemitem> in JBoss Portal Platform. The agent is able to read the token from the cookie and perform its validation because the portal is running in the same domain. - </para> - <para> - This is not possible when the JBoss Portal Platform server and the OpenAM server are running in different domains and cannot share cookies. OpenAM provides the <systemitem>CDCServlet</systemitem> to solve this situation. Authenticated users can send requests to this servlet and the servlet responds with an encoded SAML message containing the SSO token and other information required to authenticate. The portal agent is then able to parse and validate the message, obtain the SSO token and establish the <systemitem>iPlanetDirectoryPro</systemitem> cookie for the domain where JBoss Portal Platform is deployed. Once the OpenAM agent on the portal side has token, it can perform further validation of this token and finish authentication of the user. - </para> - <para> - Detailed information about the <systemitem>CDCServlet</systemitem> servlet can be found in <ulink url="http://docs.oracle.com/cd/E19575-01/820-3746/gipjl/index.html&q... OpenSSO Enterprise Deployment Planning Guide</ulink>. - </para> - <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Crossdomainauthenticationconfiguration"> - <title>Cross-domain Authentication Configuration</title> - <para> - For the purpose of this example, we will assume that the OpenAM server is deployed on the <literal>opensso.mydomain.com</literal> host and the JBoss Portal Platform server on the <literal>portal.yourdomain.com</literal> host. - </para> - <para> - If you want to simulate this configuration on a single machine, you can do it by configuring virtual hosts. On Linux, this can be achieved by editing the <code>/etc/hosts</code> file and adding records similar to the following, with the IP addresses changed accordingly: - </para> - <para> + <para> + Most of the properties are already described for CAS integration in <xref linkend="sect-CAS_Configuring_the_Platform"/>, so you can refer to that section for detailed information. + </para> + <para> + Values of some properties are different with OpenAM, specifically the URLs for login/logout redirection, the logout filter class and the <code>gatein.sso.server.url</code> property, which points to the location of the OpenAM server. The <code>gatein.sso.openam.realm</code> value points to the realm created on the OpenAM server in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-ConfigurerealminOpenAMUI"/>. + </para> + <para> + With all the previously described configuration, all links redirecting users to authentication pages will redirect them to the OpenAM authentication form. On the OpenAM side, users will be able to log in to the <literal>gatein</literal> realm using their JBoss Portal Platform credentials. + </para> + <para> + <figure> + <title>OpenAM Login Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/AuthenticationAndIdentity/SSO/openam.png"/> + </imageobject> + </mediaobject> + </figure> + </para> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-CrossdomainauthenticationwithOpenAM"> + <title>Cross-domain Authentication with OpenAM</title> + <para> + The configuration described in <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-OpenAMserversetup"/> and <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-SetuptheOpenAMclient"/> assumes that JBoss Portal Platform and OpenAM are deployed on the same server or in the same DNS domain. + </para> + <para> + In such an environment, OpenAM adds the <systemitem>iPlanetDirectoryPro</systemitem> cookie for the shared domain to the client browser. It stores the authentiction token in the cookie and performs redirection to the <systemitem>OpenSSOAgent</systemitem> in JBoss Portal Platform. The agent is able to read the token from the cookie and perform its validation because the portal is running in the same domain. + </para> + <para> + This is not possible when the JBoss Portal Platform server and the OpenAM server are running in different domains and cannot share cookies. OpenAM provides the <systemitem>CDCServlet</systemitem> to solve this situation. Authenticated users can send requests to this servlet and the servlet responds with an encoded SAML message containing the SSO token and other information required to authenticate. The portal agent is then able to parse and validate the message, obtain the SSO token and establish the <systemitem>iPlanetDirectoryPro</systemitem> cookie for the domain where JBoss Portal Platform is deployed. Once the OpenAM agent on the portal side has token, it can perform further validation of this token and finish authentication of the user. + </para> + <para> + Detailed information about the <systemitem>CDCServlet</systemitem> servlet can be found in <ulink url="http://docs.oracle.com/cd/E19575-01/820-3746/gipjl/index.html&q... OpenSSO Enterprise Deployment Planning Guide</ulink>. + </para> + <procedure id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenAM-Crossdomainauthenticationconfiguration"> + <title>Cross-domain Authentication Configuration</title> + <para> + For the purpose of this example, we will assume that the OpenAM server is deployed on the <literal>opensso.mydomain.com</literal> host and the JBoss Portal Platform server on the <literal>portal.yourdomain.com</literal> host. + </para> + <para> + If you want to simulate this configuration on a single machine, you can do it by configuring virtual hosts. On Linux, this can be achieved by editing the <code>/etc/hosts</code> file and adding records similar to the following, with the IP addresses changed accordingly: + </para> + <para> <programlisting> opensso.mydomain.com 192.168.2.7 portal.yourdomain.com 10.11.12.13 </programlisting> - </para> - <step> - <para> - On the JBoss Portal Platform side, single sign-on configuration in the <code>configuration.properties</code> file needs to be specified as follows: - </para> -<programlisting> + </para> + <step> + <para> + On the JBoss Portal Platform side, single sign-on configuration in the <code>configuration.properties</code> file needs to be specified as follows: + </para> + <programlisting> # SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} @@ -1517,139 +1297,143 @@ gatein.sso.filter.login.openamcdc.enabled=true gatein.sso.filter.login.sso.url=${gatein.sso.server.url}/cdcservlet </programlisting> - <para> - As we need to redirect requests to the <systemitem>CDCServlet</systemitem>, the <code>gatein.sso.filter.login.sso.url</code> property points to the URL of the servlet. It is also necessary to use a modified version of the <code>LoginRedirectFilter</code> interceptor. That is why the <code>gatein.sso.filter.login.openamcdc.enabled</code> value is changed to <literal>true</literal> and the <code>gatein.sso.filter.login.enabled</code> value is now set to <literal>false</literal>. - </para> - </step> - <step> - <para> - Access the OpenAM user interface at <ulink url="http://opensso.mydomain.com:8888/opensso"/> and log in as <systemitem class="username">amadmin</systemitem>. - </para> - </step> - <step> - <para> - Navigate to <menuchoice><guimenu>Access Control</guimenu><guimenuitem>"gatein" realm</guimenuitem> <guimenuitem>Agents</guimenuitem><guimenuitem>Web</guimenuitem></menuchoice>. - </para> - </step> - <step> - <para>Create a new web agent through the wizard using the following properties:</para> - <itemizedlist> - <listitem> - <para><guilabel>Name</guilabel>: GateInAgent</para> - </listitem> - <listitem> - <para><guilabel>Password</guilabel>: A password of your choice.</para> - </listitem> - <listitem> - <para><guilabel>Configuration</guilabel>: Centralized</para> - </listitem> - <listitem> - <para> - <guilabel>Server URL</guilabel>: <ulink url="http://opensso.mydomain.com:8888/opensso"/> - </para> - </listitem> - <listitem> - <para> - <guilabel>Agent URL</guilabel>: <ulink url="http://portal.yourdomain.com:8080"/> - </para> - </listitem> - </itemizedlist> - <para> - Creating this agent is required for the <systemitem>CDCServlet</systemitem> to work properly. If you have more portal servers on different hosts, you may want to create an agent for each of them. Please refer to <ulink url="http://openam.forgerock.org/doc/admin-guide/index.html">... Administration Guide</ulink> for more details. - </para> - </step> - </procedure> - </section> - </section> - - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> - <title>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)</title> - <para> + <para> + As we need to redirect requests to the <systemitem>CDCServlet</systemitem>, the <code>gatein.sso.filter.login.sso.url</code> property points to the URL of the servlet. It is also necessary to use a modified version of the <code>LoginRedirectFilter</code> interceptor. That is why the <code>gatein.sso.filter.login.openamcdc.enabled</code> value is changed to <literal>true</literal> and the <code>gatein.sso.filter.login.enabled</code> value is now set to <literal>false</literal>. + </para> + </step> + <step> + <para> + Access the OpenAM user interface at <ulink url="http://opensso.mydomain.com:8888/opensso"/> and log in as <systemitem class="username">amadmin</systemitem>. + </para> + </step> + <step> + <para> + Navigate to <menuchoice> + <guimenu>Access Control</guimenu> + <guimenuitem>&quot;gatein&quot; realm</guimenuitem> + <guimenuitem>Agents</guimenuitem> + <guimenuitem>Web</guimenuitem> + </menuchoice>. + </para> + </step> + <step> + <para>Create a new web agent through the wizard using the following properties:</para> + <itemizedlist> + <listitem> + <para><guilabel>Name</guilabel>: GateInAgent</para> + </listitem> + <listitem> + <para><guilabel>Password</guilabel>: A password of your choice.</para> + </listitem> + <listitem> + <para><guilabel>Configuration</guilabel>: Centralized</para> + </listitem> + <listitem> + <para> + <guilabel>Server URL</guilabel>: <ulink url="http://opensso.mydomain.com:8888/opensso"/> + </para> + </listitem> + <listitem> + <para> + <guilabel>Agent URL</guilabel>: <ulink url="http://portal.yourdomain.com:8080"/> + </para> + </listitem> + </itemizedlist> + <para> + Creating this agent is required for the <systemitem>CDCServlet</systemitem> to work properly. If you have more portal servers on different hosts, you may want to create an agent for each of them. Please refer to <ulink url="http://openam.forgerock.org/doc/admin-guide/index.html">... Administration Guide</ulink> for more details. + </para> + </step> + </procedure> + </section> + </section> + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> + <title>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)</title> + <para> The Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) uses desktop credentials provided during desktop authentication to transparently authenticate a portal user through a web browser. - </para> - <para> - Let's illustrate this mechanism on a typical use case: - </para> - <procedure> - <step> - <para> + </para> + <para> + Let&apos;s illustrate this mechanism on a typical use case: + </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 launches a web browser to access a web application that is hosted on JBoss Portal Platform and uses JBoss Negotiation. </para> - </step> - <step> - <para> + </step> + <step> + <para> The browser transfers the desktop credentials to the web application. </para> - </step> - <step> - <para> - JBoss Portal Platform uses background GSS messages to validate the user's Kerberos ticket with the Active Directory (or another Kerberos server). + </step> + <step> + <para> + JBoss Portal Platform uses background GSS messages to validate the user&apos;s Kerberos ticket with the Active Directory (or another Kerberos server). </para> - </step> - <step> - <para> + </step> + <step> + <para> The user experiences a seamless sign-on 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> This section describes the steps to set up a Kerberos server on Linux. The server will then be used for SPNEGO authentication against JBoss Portal Platform. - </para> - <note> - <para> + </para> + <note> + <para> The procedure below only describes the basic steps to configure a SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and an Active Directory domain, you can proceed to <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"/> to see how SPNEGO can be integrated with JBoss Portal Platform. - </para> - <para> + </para> + <para> Kerberos setup is also dependent on your Linux distribution, so the steps can be slightly different in your environment. </para> - </note> - <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> - <title>Configuring the SPNEGO Server</title> - <step> - <para> - Ensure correct hostname to IP address mapping on the machine where Kerberos and JBoss Portal Platform are running. For example, if the machine's IP address is <literal>192.168.1.88</literal> and you want it to be accessed under the <literal>server.local.network</literal> hostname, add the following line to the <emphasis role="bold">/etc/hosts</emphasis> file: + </note> + <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> + <title>Configuring the SPNEGO Server</title> + <step> + <para> + Ensure correct hostname to IP address mapping on the machine where Kerberos and JBoss Portal Platform are running. For example, if the machine&apos;s IP address is <literal>192.168.1.88</literal> and you want it to be accessed under the <literal>server.local.network</literal> hostname, add the following line to the <emphasis role="bold">/etc/hosts</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: <package>krb5-admin-server</package>, <package>krb5-kdc</package>, <package>krb5-config</package>, <package>krb5-user</package>, <package>krb5-clients</package>, and <package>krb5-rsh-server</package>. </para> - </step> - <step> - <para> + </step> + <step> + <para> Edit the Kerberos configuration in the <emphasis role="bold">/etc/krb5.config</emphasis> file: - </para> - <itemizedlist> - <listitem> - <para> + </para> + <itemizedlist> + <listitem> + <para> Uncomment the following lines: </para> -<programlisting> + <programlisting> default_tgs_enctypes = rc4-hmac default_tkt_enctypes = rc4-hmac permitted_enctypes = rc4-hmac </programlisting> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Add <emphasis role="bold">local.network</emphasis> as a default realm, add it to the list of realms, and remove the remaining realms. The resulting content of the file will be as follows: </para> -<programlisting> + <programlisting> [libdefaults] default_realm = LOCAL.NETWORK @@ -1702,19 +1486,19 @@ krb4_convert = true krb4_get_tickets = false </programlisting> - </listitem> - </itemizedlist> - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Modify KDC configuration. - </para> - <itemizedlist> - <listitem> - <para> - Edit the <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> file as shown below: - </para> -<programlisting> + </para> + <itemizedlist> + <listitem> + <para> + Edit the <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> file as shown below: + </para> + <programlisting> [kdcdefaults] kdc_ports = 750,88 @@ -1736,327 +1520,327 @@ kdc = FILE:/tmp/kdc.log admin_server = FILE:/tmp/kadmin.log </programlisting> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Create the <filename>krb5kdc</filename> and <filename>krb5logs</filename> directories according to the paths used in the KDC configuration file. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Create a KDC database. </para> -<programlisting> + <programlisting> sudo krb5_newrealm </programlisting> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Start the KDC and Kerberos servers. </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> + </para> + <itemizedlist> + <listitem> + <para> Start an interactive <literal>kadmin</literal> session and create the necessary principals. </para> -<programlisting> + <programlisting> sudo kadmin.local </programlisting> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> Add the JBoss Portal Platform machine and keytab file. </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 Portal Platform user accounts and enter a password for each of them. </para> -<programlisting> + <programlisting> addprinc john addprinc demo addprinc root </programlisting> - </listitem> - </itemizedlist> - </step> - <step> - <para> + </listitem> + </itemizedlist> + </step> + <step> + <para> Issue the following command to test your setup: </para> -<programlisting> + <programlisting> kinit -A demo </programlisting> - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> If everything is set up well, you are required to enter the password created for the <literal>demo</literal> user in the previous step. - </para> - <para> - Without the <command>-A</command> option, the Kerberos ticket validation would involve reverse DNS lookups, which can be difficult to debug with certain network DNS configurations. This is a production level security feature and it is not necessary to use it in a development environment. In production environment, it is recommended to avoid using the <command>-A</command> option. + </para> + <para> + Without the <command>-A</command> option, the Kerberos ticket validation would involve reverse DNS lookups, which can be difficult to debug with certain network DNS configurations. This is a production level security feature and it is not necessary to use it in a development environment. In production environment, it is recommended to avoid using the <command>-A</command> option. </para> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> After successful login to Kerberos, you can display your Kerberos ticket using the following command: </para> -<programlisting> + <programlisting> klist </programlisting> - </listitem> - <listitem> - <para> + </listitem> + <listitem> + <para> If you want to log out and destroy your Kerberos ticket, issue the following 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>Client Configuration</title> - <para> - After performing the server configuration described in <xref linkend="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration" />, you need to enable negotiated authentication in web browsers on client machines from which users will authenticate. + </listitem> + </itemizedlist> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> + <title>Client Configuration</title> + <para> + After performing the server configuration described in <xref linkend="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"/>, you need to enable negotiated authentication in web browsers on client machines from which users will authenticate. </para> - <para> - <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Firefox" /> describes how negotiated authentication can be enabled in Mozilla Firefox. For instructions on enabling negotiated authentication in a different browser, consult the browser's documentation. - </para> - <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Firefox"> - <title>Enabling Negotiated Authentication in Mozilla Firefox</title> - <step> - <para> + <para> + <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Firefox"/> describes how negotiated authentication can be enabled in Mozilla Firefox. For instructions on enabling negotiated authentication in a different browser, consult the browser&apos;s documentation. + </para> + <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Firefox"> + <title>Enabling Negotiated Authentication in Mozilla Firefox</title> + <step> + <para> Start Mozilla Firefox and enter <literal>about:config</literal> into the address field. </para> - </step> - <step> - <para> + </step> + <step> + <para> Search for the <literal>network.negotiate-auth</literal> preference and set its value as follows: </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> - </section> - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> - <title>JBoss Portal Platform Configuration</title> - <para> + </step> + </procedure> + </section> + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> + <title>JBoss Portal Platform Configuration</title> + <para> JBoss Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop single sign-on for the portal. The following procedure describes how to integrate SPNEGO with JBoss Portal Platform. - </para> - <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> - <title>Configuring SPNEGO Integration with JBoss Portal Platform</title> - <step> - <para> + </para> + <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> + <title>Configuring SPNEGO Integration with JBoss Portal Platform</title> + <step> + <para> Modify the <literal># SSO</literal> section of the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/gatein/configuration.properties</filename> file, replacing the original content with the following properties: </para> -<programlisting> + <programlisting> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text"/> </programlisting> - <para> + <para> The list below explains the meaning of individual properties: <variablelist> - <varlistentry> - <term>gatein.sso.enabled</term> - <listitem> - <para> - This is a general property used to inform JBoss Portal Platform that clicking the <guibutton>Sign in</guibutton> link will redirect users to a URL ending with the <literal>/portal/dologin</literal> suffix. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.callback.enabled</term> - <listitem> - <para> - This property can be set to <literal>false</literal> as REST callbacks are not required for SPNEGO integration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.skip.jsp.redirection</term> - <listitem> - <para> - This property must be set to <literal>false</literal> for SPNEGO integration, especially to ensure fallback to FORM authentication. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.login.module.enabled</term> - <listitem> - <para> - This property can be set to <literal>false</literal> as a different set of login modules is needed for SPNEGO integration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.filter.login.sso.url</term> - <listitem> - <para> - This value ensures that clicking the <guibutton>Sign in</guibutton> link will redirect users to the <literal>/portal/dologin</literal> URL, which is a secured URL declared in the <filename>security-constraint section of JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/web.xml</filename> file, allowing the <systemitem>GateInNegotiationAuthenticator</systemitem> valve to intercept the HTTP request. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.filter.logout.enabled</term> - <term>gatein.sso.filter.initiatelogin.enabled</term> - <listitem> - <para> - These properties can be set to <literal>false</literal> as the logout filter and the <systemitem>InitiateLoginFilter</systemitem> are not needed for SPNEGO integration. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.valve.enabled</term> - <listitem> - <para> - SPNEGO integration requires a custom Tomcat valve to intercept HTTP requests for secured URLs. The <systemitem>SSODelegateValve</systemitem> is defined in the <filename>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/jboss-web.xml</filename> file and is used only if this option is set to <literal>true</literal>. The purpose of the valve is to delegate the real work to another valve declared in the <literal>gatein.sso.valve.class</literal> property. This eliminates the need to edit configuration in the <filename>jboss-web.xml</filename> file. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.valve.class</term> - <listitem> - <para> - The delegate valve for SPNEGO is <systemitem>org.gatein.sso.spnego.GateInNegotiationAuthenticator</systemitem>. It is used to establish identity of the client by exchanging several handshakes with client browser. The valve is able to obtain and parse an SPNEGO token and resend it to the JAAS layer, where login modules (especially the <systemitem>SPNEGOLoginModule</systemitem>) are able to verify the validity of the wrapped Kerberos token and establish user identity at the JBoss Portal Platform layer. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </step> - <step> + <varlistentry> + <term>gatein.sso.enabled</term> + <listitem> <para> + This is a general property used to inform JBoss Portal Platform that clicking the <guibutton>Sign in</guibutton> link will redirect users to a URL ending with the <literal>/portal/dologin</literal> suffix. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.callback.enabled</term> + <listitem> + <para> + This property can be set to <literal>false</literal> as REST callbacks are not required for SPNEGO integration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.skip.jsp.redirection</term> + <listitem> + <para> + This property must be set to <literal>false</literal> for SPNEGO integration, especially to ensure fallback to FORM authentication. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.login.module.enabled</term> + <listitem> + <para> + This property can be set to <literal>false</literal> as a different set of login modules is needed for SPNEGO integration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.login.sso.url</term> + <listitem> + <para> + This value ensures that clicking the <guibutton>Sign in</guibutton> link will redirect users to the <literal>/portal/dologin</literal> URL, which is a secured URL declared in the <filename>security-constraint section of JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/web.xml</filename> file, allowing the <systemitem>GateInNegotiationAuthenticator</systemitem> valve to intercept the HTTP request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.filter.logout.enabled</term> + <term>gatein.sso.filter.initiatelogin.enabled</term> + <listitem> + <para> + These properties can be set to <literal>false</literal> as the logout filter and the <systemitem>InitiateLoginFilter</systemitem> are not needed for SPNEGO integration. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.valve.enabled</term> + <listitem> + <para> + SPNEGO integration requires a custom Tomcat valve to intercept HTTP requests for secured URLs. The <systemitem>SSODelegateValve</systemitem> is defined in the <filename>JPP_SERVER/gatein/gatein.ear/portal.war/WEB-INF/jboss-web.xml</filename> file and is used only if this option is set to <literal>true</literal>. The purpose of the valve is to delegate the real work to another valve declared in the <literal>gatein.sso.valve.class</literal> property. This eliminates the need to edit configuration in the <filename>jboss-web.xml</filename> file. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>gatein.sso.valve.class</term> + <listitem> + <para> + The delegate valve for SPNEGO is <systemitem>org.gatein.sso.spnego.GateInNegotiationAuthenticator</systemitem>. It is used to establish identity of the client by exchanging several handshakes with client browser. The valve is able to obtain and parse an SPNEGO token and resend it to the JAAS layer, where login modules (especially the <systemitem>SPNEGOLoginModule</systemitem>) are able to verify the validity of the wrapped Kerberos token and establish user identity at the JBoss Portal Platform layer. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </step> + <step> + <para> Modify configuration of the <systemitem>security</systemitem> subsystem in the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone.xml</filename> file: </para> - <substeps> - <step> - <para> - Rename the existing <literal>gatein-domain</literal> security domain to <literal>gatein-form-auth-domain</literal>. - </para> - </step> - <step> - <para> - Add a new definition of the <literal>gatein-domain</literal> security domain. - </para> - </step> - <step> - <para> - Add a new security domain called <literal>host</literal>. Values of the following properties need to be specified in accordance with your environment setup: - </para> - <para> - <variablelist> - <varlistentry> - <term>principal</term> - <listitem> - <para> - The HTTP server principal specified in your kerberos keytab. In <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics" />, we used the <literal>LOCAL.NETWORK</literal> Kerberos realm and the <literal>server.local.network</literal> host and subsequently added the <literal&gt;HTTP/server.local.network(a)LOCAL.NETWORK&lt;/literal&gt; principal to the keytab. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>keyTab</term> - <listitem> - <para> - The path to the file with your Kerberos keytab. In <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics" />, we used the <filename>/etc/krb5.keytab</filename> location. Please note that this file should be readable by the user under whose account JBoss Portal Platform is executed. Generally, Kerberos keytab files should not be readable by normal OS users as they contain encrypted keys of server principals. Consult Kerberos documentation for more details. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>debug</term> - <listitem> - <para> - Enabling this option adds more log messages into JBoss Portal Platform console and log file. It is useful to have this option enabled during configuration, but it is advised to disable it in production to avoid unnecessarily large server logs. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> - </step> - </substeps> - <para> - The code extract below shows the expected result of the security domain configuraion. - </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> + <substeps> + <step> + <para> + Rename the existing <literal>gatein-domain</literal> security domain to <literal>gatein-form-auth-domain</literal>. + </para> + </step> + <step> + <para> + Add a new definition of the <literal>gatein-domain</literal> security domain. + </para> + </step> + <step> + <para> + Add a new security domain called <literal>host</literal>. Values of the following properties need to be specified in accordance with your environment setup: + </para> + <para> + <variablelist> + <varlistentry> + <term>principal</term> + <listitem> + <para> + The HTTP server principal specified in your kerberos keytab. In <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"/>, we used the <literal>LOCAL.NETWORK</literal> Kerberos realm and the <literal>server.local.network</literal> host and subsequently added the <literal&gt;HTTP/server.local.network(a)LOCAL.NETWORK&lt;/literal&gt; principal to the keytab. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>keyTab</term> + <listitem> + <para> + The path to the file with your Kerberos keytab. In <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"/>, we used the <filename>/etc/krb5.keytab</filename> location. Please note that this file should be readable by the user under whose account JBoss Portal Platform is executed. Generally, Kerberos keytab files should not be readable by normal OS users as they contain encrypted keys of server principals. Consult Kerberos documentation for more details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>debug</term> + <listitem> + <para> + Enabling this option adds more log messages into JBoss Portal Platform console and log file. It is useful to have this option enabled during configuration, but it is advised to disable it in production to avoid unnecessarily large server logs. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </step> + </substeps> + <para> + The code extract below shows the expected result of the security domain configuraion. + </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> While logged in as a user with read permissions for the Kerberos keytab file, start JBoss Portal Platform using the following command: </para> -<programlisting> + <programlisting> ./standalone.sh -Djava.security.krb5.realm=LOCAL.NETWORK -Djava.security.krb5.kdc=server.local.network -b server.local.network </programlisting> - </step> - </procedure> - </section> - <section> - <title>SPNEGO Configuration Testing</title> - <para> - Once you have performed the configuration above, you can follow <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing"/> to verify that the configured authentication is functional. - </para> - <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing"> - <title>Testing the SPNEGO Configuration</title> - <step> - <para> + </step> + </procedure> + </section> + <section> + <title>SPNEGO Configuration Testing</title> + <para> + Once you have performed the configuration above, you can follow <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing"/> to verify that the configured authentication is functional. + </para> + <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing"> + <title>Testing the SPNEGO Configuration</title> + <step> + <para> Log in to Kerberos using the following command: </para> -<programlisting> + <programlisting> kinit -A demo </programlisting> - </step> - <step> - <para> + </step> + <step> + <para> In a browser, access <ulink url="http://server.local.network:8080/portal">http://server.local.network:8080/portal</ulink> and click the <guibutton>Sign In</guibutton> link in the top menu of the portal. If the authentication is configured correctly, you will be automatically signed in as the <literal>demo</literal> user. </para> - </step> - <step> - <para> + </step> + <step> + <para> Destroy the previously obtained Kerberos ticket using the following command: <programlisting> kdestroy </programlisting> - </para> - </step> - <step> - <para> - In the browser, log out and log back in. In case of correct configuration, you will be redirected to the login screen of JBoss Portal Platform. This happens because you no longer have an active Kerberos ticket and a fallback to the standard FORM authentication occurred. - </para> - </step> - </procedure> - </section> - <section> + </para> + </step> + <step> + <para> + In the browser, log out and log back in. In case of correct configuration, you will be redirected to the login screen of JBoss Portal Platform. This happens because you no longer have an active Kerberos ticket and a fallback to the standard FORM authentication occurred. + </para> + </step> + </procedure> + </section> + <section> <title>Additional Configuration</title> - <para> - </para> - <section> - <title>Disabling Fallback to FORM Authentication</title> - <para> - As demonstrated in <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing" />, users trying to sign in without a valid Kerberos ticket are automatically redirected to the JBoss Portal Platform logon page. There, they can perform standard FORM authentication using their user name and password. - </para> - <para> - If you want to disable FORM authentication to allow only users with a valid Kerberos ticket to sign in, you need to comment out the <parameter>usernamePasswordDomain</parameter> option in the <literal>SPNEGOLoginModule</literal> configuration in the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone.xml</filename> file. - </para> -<programlisting language="XML"><![CDATA[<login-module + <para> + </para> + <section> + <title>Disabling Fallback to FORM Authentication</title> + <para> + As demonstrated in <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-SPNEGO_Testing"/>, users trying to sign in without a valid Kerberos ticket are automatically redirected to the JBoss Portal Platform logon page. There, they can perform standard FORM authentication using their user name and password. + </para> + <para> + If you want to disable FORM authentication to allow only users with a valid Kerberos ticket to sign in, you need to comment out the <parameter>usernamePasswordDomain</parameter> option in the <literal>SPNEGOLoginModule</literal> configuration in the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone.xml</filename> file. + </para> + <programlisting language="XML"><![CDATA[<login-module code="org.gatein.sso.spnego.SPNEGOLoginModule" flag="requisite"> <module-option name="password-stacking" value="useFirstPass"/> <module-option name="serverSecurityDomain" value="host"/> @@ -2064,30 +1848,30 @@ <!--<module-option name="usernamePasswordDomain" value="gatein-form-auth-domain"/>--> </login-module>]]> </programlisting> - </section> - <section> - <title>Enabling Logging</title> - <para> - To enable logging of events related to SPNEGO authentication, you can add the following entries to the <systemitem>logging</systemitem> subsystem in the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone.xml</filename> file: - </para> -<programlisting language="XML"><![CDATA[<logger category="org.gatein.sso"> + </section> + <section> + <title>Enabling Logging</title> + <para> + To enable logging of events related to SPNEGO authentication, you can add the following entries to the <systemitem>logging</systemitem> subsystem in the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone.xml</filename> file: + </para> + <programlisting language="XML"><![CDATA[<logger category="org.gatein.sso"> <level name="TRACE"/> </logger> <logger category="org.jboss.security.negotiation"> <level name="TRACE"/> </logger>]]> -</programlisting> - <para> - Increased logging of Kerberos events to standard output can be enabled by launching JBoss Portal Platform with the <command>-Dsun.security.krb5.debug=true</command> option. - </para> -<programlisting> +</programlisting> + <para> + Increased logging of Kerberos events to standard output can be enabled by launching JBoss Portal Platform with the <command>-Dsun.security.krb5.debug=true</command> option. + </para> + <programlisting> ./standalone.sh -Djava.security.krb5.realm=LOCAL.NETWORK -Djava.security.krb5.kdc=server.local.network -b server.local.network -Dsun.security.krb5.debug=true -</programlisting> - </section> +</programlisting> </section> - </section> - <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> - <title>Single Sign-On in a Cluster</title> + </section> + </section> + <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve"> + <title>Single Sign-On in a Cluster</title> <!-- Source Metadata URL: https://issues.jboss.org/browse/JBQA-4530 Author [w/email]: Marek Posolda (mposolda(a)redhat.com) @@ -2097,118 +1881,101 @@ voiii URL: https://issues.jboss.org/browse/JBEPP-615 Author [w/email]: Marek Posolda (mposolda(a)redhat.com) - --> - <para> + --> <para> In a cluster, the JBoss SSO valve can be used to authenticate a user on one JBoss Portal Platform node and have that authentication automatically carried across to other nodes in the cluster. </para> - - <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve-Default_Config"> - <title>Default Configuration</title> - - <para> + <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve-Default_Config"> + <title>Default Configuration</title> + <para> The JBoss SSO valve is enabled by default. The enablement is ensured by the following JBoss Web subsystem configuration entry in the <filename>JPP_SERVER/standalone/configuration/standalon-ha.xml</filename> file: </para> -<programlisting language="XML"><![CDATA[ + <programlisting language="XML"><![CDATA[ <sso cache-container="web" cache-name="sso" reauthenticate="false" /> ]]></programlisting> - <para> + <para> When a loadbalancer is used in a cluster, no further configuration is needed to set up single sign-on. All JBoss Portal Platform servers in the cluster are accessed through the same URL, which is the URL of the loadbalancer. Automatic single sign-on is performed when the loadbalancer redirects client requests to individual nodes in the cluster. </para> - </section> - - <section> - <title>Clustered Single-Sign On in a Shared DNS Domain</title> - - <para> + </section> + <section> + <title>Clustered Single-Sign On in a Shared DNS Domain</title> + <para> If multiple JBoss Portal Platform servers are accessed through different URLs in the same DNS domain, single sign-on can be configured by adding the <parameter>domain</parameter> parameter to the <parameter>sso</parameter> configuration entry. </para> -<programlisting language="XML"><![CDATA[ + <programlisting language="XML"><![CDATA[ <sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/> ]]></programlisting> - <para> + <para> The parameter must be added to the entry on all servers in the cluster and the name of the shared DNS domain must be specified as its value. This configuration ensures that the <parameter>JSESSIONIDSSO</parameter> cookie will be scoped to the specified domain, which is otherwise scoped only to the host where the initial authentication was performed. </para> - - <para> + <para> The following procedure demonstrates how to configure and test single sign-on for two JBoss Portal Platform servers running in a shared domain on the same physical Linux machine. </para> - - <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> - <title>Configuring and Testing Single-Sign On in a Shared DNS Domain</title> - - <step> - <para> + <procedure id="proc-Reference_Guide-Enabling_SSO_using_JBoss_SSO_Valve-Testing_the_SSO_Valve"> + <title>Configuring and Testing Single-Sign On in a Shared DNS Domain</title> + <step> + <para> Add the following lines to the <emphasis role="bold">/etc/hosts</emphasis> file. Modify the IP addresses in accordance with the IP addresses of the two JBoss Portal Platform servers. </para> -<programlisting> + <programlisting> 127.0.1.1 machine1.yourdomain.com 127.0.1.2 machine2.yourdomain.com </programlisting> - </step> - - <step> - <para> + </step> + <step> + <para> On both servers, open the <filename><replaceable>JPP_SERVER</replaceable>/standalone/configuration/standalone-ha.xml</filename> file. Add the <parameter>domain</parameter> parameter to the <parameter>sso</parameter> entry and specify the name of the shared DNS domain in its value. </para> -<programlisting language="XML"><![CDATA[ + <programlisting language="XML"><![CDATA[ <sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/> ]]></programlisting> - </step> - - <step> - <para> + </step> + <step> + <para> Start the first server using the following command: </para> -<programlisting> + <programlisting> ./standalone.sh -b machine1.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node1 </programlisting> - </step> - - <step> - <para> + </step> + <step> + <para> Start the second server using the following command: </para> -<programlisting> + <programlisting> ./standalone.sh -b machine2.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node2 </programlisting> - </step> - - <step> - <para> + </step> + <step> + <para> Access the first server at <ulink url="http://machine1.yourdomain.com:8080/portal">http://machine1.yourdomain.com:8080/portal</ulink> and log in as a user. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Access the second server at <ulink url="http://machine2.yourdomain.com:8080/portal">http://machine2.yourdomain.com:8080/portal</ulink>. When the page loads, you will be automatically logged in with the same user account that you used on the first server. </para> - </step> - - <step> - <para> + </step> + <step> + <para> Log out on any of the two servers. Then switch to the other server and verify that you have been logged out of this server as well. </para> - </step> - </procedure> - </section> - - <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve-Other_Web_Apps"> - <title>Reauthentication</title> - - <para> + </step> + </procedure> + </section> + <section id="sect-SSO_Single_Sign_On_-Enabling_SSO_using_JBoss_SSO_Valve-Other_Web_Apps"> + <title>Reauthentication</title> + <para> The JBoss SSO valve can also be used to authenticate with any other web application. If that application uses the same roles as the main JBoss Portal Platform instance, no further configuration is required. Because the JBoss SSO valve includes the same JAAS principal in all HTTP requests, even in requests to other web applications, matching roles ensure successful authentication with those applications. </para> - - <para> + <para> To enable single sing-on authentication with an application that uses different roles, you need to set the <parameter>reauthenticate</parameter> parameter of the <parameter>sso</parameter> JBoss Web subsystem configuration entry to <literal>true</literal>. </para> -<programlisting language="XML"><![CDATA[ + <programlisting language="XML"><![CDATA[ <sso cache-container="web" cache-name="sso" reauthenticate="true" /> ]]></programlisting> - <para> + <para> The <literal>true</literal> value ensures that reauthentication with user credentials will be performed against the web application&apos;s security domain in each HTTP request. This will enforce creation of a new principal with updated roles for the web application. As user credentials are used for authentication in this case, it is required that the same user credentials exist in both the web application and the JBoss Portal Platform instance. </para> - </section> - </section> - </chapter> + </section> + </section> +</chapter> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalConfiguration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -98,7 +98,7 @@ Once you have created a custom portal that suits your needs, you may wish to disable a portal that is no longer required. </para> <task> - <title>Task: Disable a portal in EPP 5</title> + <title>Task: Disable a portal in JBoss Portal Platform 5</title> <tasksummary> <para> The procedure below will show you how to disable an unused portal in a JBoss Portal Platform instance. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/DefaultPortalNavigationConfiguration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -28,7 +28,7 @@ </listitem> </itemizedlist> <para> - These navigations are configured using the standard XML syntax in the file: <filename>02portal.war/WEB-INF/conf/portal/portal-configuration.xml</filename>. + These navigations are configured using the standard XML syntax in the file: <filename>portal.war/WEB-INF/conf/portal/portal-configuration.xml</filename>. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/default144.xml" parse="text"/></programlisting> <para> @@ -114,7 +114,7 @@ The portal navigation incorporates the pages that can be accessed even when a user is not logged in (assuming the applicable permissions allow public access). For example; several portal navigations could be used when a company has multiple trademarks, and websites are set up for each of them. </para> <para> - The <emphasis>Classic</emphasis> portal is configured by three XML files in the <filename>02portal.war:/WEB-INF/conf/portal/portal/classic</filename> directory: + The <emphasis>Classic</emphasis> portal is configured by three XML files in the <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/portal/portal/classic</filename> directory: </para> <variablelist> <varlistentry> @@ -166,16 +166,15 @@ </warning> </listitem> </varlistentry> - <varlistentry> + <varlistentry> <term>pages.xml</term> <listitem> <para> - This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags (some usage examples of container tags can be found in <filename>02portal.war/WEB-INF/conf/portal/portal/sharedlayout.xml</filename>). + This configuration file structure is very similar to <filename>portal.xml</filename> and it can also contain container tags (some usage examples of container tags can be found in <filename>portal.war/WEB-INF/conf/portal/portal/sharedlayout.xml</filename>). </para> <para> Each application can decide whether to render the portlet border, the window state, the icons, or the portlet mode. </para> - </listitem> </varlistentry> </variablelist> @@ -189,7 +188,7 @@ The group navigation menu is configured by two XML files (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). The syntax used in these files is the same as those covered in <xref linkend="sect-Reference_Guide-Portal_Navigation_Configuration-Portal_Navigation"/>. </para> <para> - They are located in <filename>02portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>02portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>). + They are located in <filename>portal.war/WEB-INF/conf/portal/group<replaceable>/group-name-path/</replaceable></filename> directory (For example; <filename>portal.war/WEB-INF/conf/portal/group/platform/administrators/</filename>). </para> </section> <section id="sect-Reference_Guide-Portal_Navigation_Configuration-User_Navigation"> @@ -198,7 +197,7 @@ User navigation is the set of nodes and pages that are owned by a user. They are part of the user&apos;s dashboard. </para> <!-- DOC NOTE: Get an answer on the below! --><!-- This Paragraph: --> <para> - Two files configure the user navigation (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). They are located in the directory &quot;<filename>02portal.war/WEB-INF/conf/portal/users/{userName}</filename>&quot;. + Two files configure the user navigation (<filename>navigation.xml</filename> and <filename>pages.xml</filename>). They are located in the directory &quot;<filename>portal.war/WEB-INF/conf/portal/users/{userName}</filename>&quot;. </para> <para> The file <filename>eXoGadgets.war/WEB-INF/gadget.xml</filename> defines the gadgets that will be available on a user dashboard. @@ -207,5 +206,5 @@ The example below shows a dashboard with all of the default gadgets included, as well as an extra currency converter gadget sourced from <ulink url="http://www.google.com/ig/directory?synd=open" type="http">Google Gadgets</ulink>. </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/PortalDevelopment_DefaultPortalNavigationConfiguration/gadgets.xml" parse="text"/></programlisting> - </section> + </section> </chapter> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/LocalizationConfiguration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -57,7 +57,7 @@ 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>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</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"/> . + The supported locales are listed in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.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. @@ -204,7 +204,7 @@ <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&apos;s webui configuration file: <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/webui-configuration.xml</filename>: + The <literal>LocalePolicy</literal> framework is enabled for portlets by configuring <literal>LocalizationLifecycle</literal> class in portal&apos;s webui configuration file: <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/webui-configuration.xml</filename>: </para> <programlisting language="XML" role="XML">&lt;application-life-cycle-listeners&gt; ... @@ -212,7 +212,7 @@ &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>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/portal/web-configuration.xml</filename>. + The default <literal>LocalePolicy</literal> implementation is installed as an eXo Kernel portal service via <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/portal/web-configuration.xml</filename>. </para> <para> The following excerpt is responsible for installing the service: @@ -244,7 +244,7 @@ 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>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename>. + <literal>LocalizationFilter</literal> is installed through the portal&apos;s web.xml file: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/web.xml</filename>. </para> <programlisting language="XML" role="XML">&lt;filter&gt; &lt;filter-name&gt;LocalizationFilter&lt;/filter-name&gt; Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortalDevelopment/Skinning.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -87,7 +87,7 @@ The default skin can also be configured using the portal configuration files. This allows the portal to have the new default skin ready for use when JBoss Portal Platform is first started. </para> <para> - The default skin of the portal is called <literal>Default</literal>. To change this value add a <literal>skin</literal> tag in the <literal>02portal.war/WEB-INF/conf/portal/portal/classic/portal.xml</literal> configuration file. + The default skin of the portal is called <literal>Default</literal>. To change this value add a <literal>skin</literal> tag in the <literal>portal.war/WEB-INF/conf/portal/portal/classic/portal.xml</literal> configuration file. </para> <para> To change the skin to <literal>MySkin</literal> you would make the following changes: @@ -406,7 +406,7 @@ </listitem> <listitem> <para> - The value of the <parameter>portlet-name</parameter> element needs to match the value of the <parameter>portlet-name</parameter> element in <filename>portlet.xml</filename>. + The value of the <parameter>portlet-name</parameter> element needs to match the value of the <parameter>portlet-name</parameter> element in <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/portlet.xml</filename>. </para> </listitem> </itemizedlist> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Global_Portlet.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -40,12 +40,12 @@ &lt;/portlet-app&gt; </programlisting> <para> - The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default, the file path is <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/gatein/portlet.xml</filename> + The path to the global <filename>portlet.xml</filename> is the value of <literal>gatein.portlet.config</literal> in the <filename>configuration.properties.xml</filename> file. By default, the file path is <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/portlet.xml</filename> </para> <section id="sect-Reference_Guide-Shared_portlet.xml-Global_Metadata_Elements"> <title>Global Metadata Elements</title> <para> - The global <filename>portlet.xml</filename> file conforms, with some restrictions, to the portlet deployment descriptor schema defined in the Portlet Specification. In this file, the following elements are supported: + The global <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/portlet.xml</filename> file conforms, with some restrictions, to the portlet deployment descriptor schema defined in the Portlet Specification. In this file, the following elements are supported: </para> <orderedlist> <listitem> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge/configuration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -7,7 +7,7 @@ <title id="Portlet_Bridge_Bridge_Configuration">Bridge Configuration</title> <section id="sect-Reference_Guide-Core_Setup_and_Configuration-portlet.xml"> <title>portlet.xml</title> - <para>To have access to all portlet 2 specification features, you must declare the portlet schema definition as prescribed in the <filename>portlet.xml</filename> file. The &lt;init-param&gt; directives are explained in more detail if required below the portlet.xml code.</para> + <para>To have access to all portlet 2 specification features, you must declare the portlet schema definition as prescribed in the <filename><replaceable>JPP_HOME</replaceable>/standalone/configuration/gatein/portlet.xml</filename> file. The &lt;init-param&gt; directives are explained in more detail if required below the <filename>portlet.xml</filename> code.</para> <para>The XML below describes the basic directives required for a JSF2 portlet. Some directives are optional, and are called-out in the file. </para> <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../extras/PortletBridge_Configuration/default197.xml" parse="text"/></programlisting> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/PortletBridge.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -28,7 +28,7 @@ </section> <section id="Portlet_Bridge_File_Locations"> <title>File Locations</title> - <remark>BZ#856417 - NEEDINFO - will we be packaging the portletbridge binaries in this folder for EPP 6? </remark> + <remark>BZ#856417 - NEEDINFO - will we be packaging the portletbridge binaries in this folder for JBoss Portal Platform 6? </remark> <para>The binaries required for Portlet Bridge applications, and example applications that can be used to learn and understand JSF applications are located in in <filename>JPP_DIST/portletbridge</filename>. </para> <para>Configuration files for Portlet Bridge are located in the following locations: </para> <itemizedlist> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/PortletDevelopment/Standard.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -121,7 +121,7 @@ This section describes how to deploy a portlet in JBoss Portal Platform. </para> <para> - An example portlet called <filename>SimplestHelloWorld</filename> is available in the <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Portal Platform sources package. + An example portlet called <filename>SimplestHelloWorld</filename> is available in the <filename>/jboss-jpp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Portal Platform sources package. </para> <section id="sect-Reference_Guide-Deploying_your_first_Portlet-Compiling"> <title>Compiling</title> @@ -306,7 +306,7 @@ <para>Obtain the JBoss Portal Platform sources package from the Customer Support portal.</para> </step> <step> - <para>Move to <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/jsphellouser</filename> </para> + <para>Move to <filename>/jboss-jpp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/jsphellouser</filename> </para> </step> <step> <para> @@ -455,7 +455,7 @@ In order to write a portlet using JSF a &apos;bridge&apos; is needed. This software allows developers to write a portlet application as if it was a JSF application. The bridge then negotiates the interactions between the two layers. </para> <para> - An example using the JBoss Portlet Bridge is available in the <filename>/jboss-epp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Portal Platform sources package. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. + An example using the JBoss Portlet Bridge is available in the <filename>/jboss-jpp-<replaceable>VERSION</replaceable>-src/portal/examples/portlets/</filename> directory of the JBoss Portal Platform sources package. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application. </para> <para> As in any JSF application, the file <literal>faces-config.xml</literal> is required. It must contain the following information: Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/exo-jcr-configuration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -54,7 +54,7 @@ JCR services are registered in the Portal container. </para> <para> - Below is an example configuration from the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. + Below is an example configuration from the <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</filename> file. </para> <programlisting language="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_Configuration/jcr-configuration.xml" parse="text"/></programlisting> <section id="sect-Reference_Guide-Portal_configuration-JCR_Configuration"> @@ -63,7 +63,7 @@ The JCR Service can use multiple <emphasis>Repositories</emphasis> and each repository can have multiple <emphasis>Workspaces</emphasis>. </para> <para> - Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + Configure the workspaces by locating the workspace you need to modify in <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> The repository configuration supports human-readable values. They are not case-sensitive. Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/multilanguage-support.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -37,7 +37,7 @@ <itemizedlist> <listitem> <para> - The configuration file to be modified for these changes is <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + The configuration file to be modified for these changes is <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> </listitem> <listitem> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/configuration/search-configuration.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -12,7 +12,7 @@ Below is an example of the configuration file that governs search behaviors. Refer to <xref linkend="sect-Reference_Guide-Search_Configuration-Global_Search_Index"/> for how searching operates in JCR and information about customized searches. </para> <para> - The JCR index configuration file is located at <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + The JCR index configuration file is located at <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> A code example is included below with a list of the configuration parameters shown below that. @@ -516,7 +516,7 @@ </para> </example> <para> - The global search index is configured in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>VERSION</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the &quot;query-handler&quot; tag. + The global search index is configured in the <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> configuration file within the &quot;query-handler&quot; tag. </para> <programlisting language="XML" role="XML">&lt;query-handler class=&quot;org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex&quot;&gt; </programlisting> @@ -616,13 +616,13 @@ </programlisting> <para> - in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: + in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename> with the new class: </para> <programlisting language="XML" role="XML">&lt;query-handler class=&quot;mypackage.indexation.MySearchIndex&gt; </programlisting> <para> - To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: + To configure an application to use a new analyzer, add the <parameter>analyzer</parameter> parameter to each query-handler configuration in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/repository-configuration.xml</filename>: </para> <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../extras/Advanced_Development_JCR_search-configuration/default69.xml" parse="text"/></programlisting> <para> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/jbosscache-configuration-templates.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -70,7 +70,7 @@ <section id="sect-Reference_Guide-JBoss_Cache_configuration-Shipped_JBoss_Cache_configuration_templates"> <title>Shipped JBoss Cache configuration templates</title> <para> - The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR&apos;s components. They are located in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. + The eXo JCR implementation is shipped with ready-to-use JBoss Cache configuration templates for JCR&apos;s components. They are located in <filename><replaceable>JPP_HOME</replaceable>/gatein/gatein.ear/portal.war/WEB-INF/conf/jcr/jbosscache</filename> directory, inside either the <filename>cluster</filename> or <filename>local</filename> directory. </para> <section id="sect-Reference_Guide-Shipped_JBoss_Cache_configuration_templates-Data_container_template"> <title>Data container template</title> Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml 2013-01-25 01:01:20 UTC (rev 9076) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/eXoJCR/jcr/searching/searching-repository-content.xml 2013-01-25 02:15:12 UTC (rev 9077) @@ -8,7 +8,7 @@ <section id="sect-Reference_Guide-Searching_Repository_Content-Introduction"> <title>Introduction</title> <para> - You can find the JCR configuration file here: <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. + You can find the JCR configuration file here: <filename><replaceable>JPP_DIST</replaceable>/gatein/gatein.ear/portal.war/portal/WEB-INF/conf/jcr/repository-configuration.xml</filename>. </para> <para> Please refer to <xref linkend="chap-Reference_Guide-Search_Configuration"/> for more information about index configuration.