[gatein-commits] gatein SVN: r8986 - epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity.

Author: smumford Date: 2012-12-10 19:56:25 -0500 (Mon, 10 Dec 2012) New Revision: 8986 Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml Log: Reformatted XML for easier reading...because Serna hates XML Modified: epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml =================================================================== --- epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-09 23:45:57 UTC (rev 8985) +++ epp/docs/branches/6.0/Reference_Guide/en-US/modules/AuthenticationAndIdentity/SSO.xml 2012-12-11 00:56:25 UTC (rev 8986) @@ -3,245 +3,312 @@ <!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> -JBoss Portal Platform provides an implementation of single sign-on (<literal>SSO</literal>) as an integration and aggregation platform. - </para> - <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> 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> + + <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> + + <para> This section will cover the implementation of four different SSO plug-ins with JBoss Portal Platform: - </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="sect-SSO_Single_Sign_On_-Central_Authentication_Service"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/> - </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> + + <itemizedlist> + <listitem> + <para> + <xref linkend="sect-SSO_Single_Sign_On_-Central_Authentication_Service"/> + </para> + </listitem> + + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"/> + </para> + </listitem> + + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"/> + </para> + </listitem> + + <listitem> + <para> + <xref linkend="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"/> + </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> - <para> + </para> + + <para> In the following scenarios this directory will be referred to as <replaceable>PORTAL_SSO</replaceable>. - </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> + + <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>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>The authentication process with CAS integration occurs in the following order:</para> - <orderedlist> - <listitem> - <para>A user visits the main portal page, and wishes to authenticate. The user clicks - <emphasis role="italics">Sign in</emphasis>. </para> - </listitem> - <listitem> - <para>Normally this action would present the 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> --> + </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> + The authentication process with CAS integration occurs in the following order: </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. + + <orderedlist> + <listitem> + <para> + A user visits the main portal page, and wishes to authenticate. The user clicks <emphasis role="italics">Sign in</emphasis>. + </para> + </listitem> + + <listitem> + <para> + Normally this action would present the portal login dialog, however with SSO integration enabled, the action redirects the user to a marker URL such as <ulink url="http://localhost:8080/portal/sso"/>. + </para> + + <para> + The portal handles this user action by calling the interceptor (Servlet filter) <emphasis role="strong">LoginRedirectFilter</emphasis>, which redirects the user seamlessly away from the <emphasis role="italics">/portal/sso</emphasis> URL to the CAS server page. + </para> + </listitem> + + <listitem> + <para> + The interceptor redirects the user to the CAS login page <ulink url="http://localhost:8888/cas/login"/> . The user enters the correct authentication information, and submits the form. + </para> + + <para> + The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with JBoss Portal Platform. Refer to <xref linkend="sect-CAS_Authentication_Plug-in"/> for specific details about this technology. + </para> + </listitem> + + <listitem> + <para> + Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as <ulink url="http://localhost:8080/portal/initiatelogin"/> . + </para> + + <para> + The <emphasis role="strong">InitiateLoginFilter</emphasis> interceptor acts on the user redirection to <emphasis role="italics">/portal/initiatelogin</emphasis> by obtaining a CAS ticket attached in the HTTP request inside the <emphasis role="italics">ticket</emphasis> parameter. The interceptor then delegates validation of this ticket to a configured <emphasis role="strong">CASAgent</emphasis> component. + </para> + </listitem> + + <listitem> + <para> + The <emphasis>CASAgent</emphasis> validates the ticket by sending a validation request to the CAS server through a configured back channel. The CAS server validates the request, and ensures it contains the user name of the authenticated user in step 3. + </para> + </listitem> + + <listitem> + <para> + After SSO validation, <emphasis role="italics">InitiateLoginFilter</emphasis> redirects the user to the portal login URL <ulink url="http://localhost:8080/portal/login"/> , which initiates JAAS authentication. + </para> + + <para> + The <emphasis role="strong">SSOLoginModule</emphasis> detects whether the user has been successfully validated by <emphasis role="italics">CASAgent</emphasis>. If this is the case, the login module obtains data about user (groups, memberships) from <emphasis role="italics">OrganizationService</emphasis> and encapsulates the details into an <emphasis role="strong">Identity</emphasis> object. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="strong">JBossAS7LoginModule</emphasis> completes the authentication request by establishing the JAAS <emphasis role="italics">Subject</emphasis>, and saves the <emphasis role="italics">Identity</emphasis> object to the <emphasis role="italics">IdentityRegistry</emphasis>. For more information about login modules, refer to <xref linkend="sect-Authentication_Authorization_Intro-Login_Modules"/>. + </para> + </listitem> + + <listitem> + <para> + After successful JAAS authentication, the user is redirected to the portal in an authenticated state. + </para> + </listitem> + </orderedlist> + + <para> + For more information about the available Login Modules shipped with the product, refer to the JBoss Enterprise Application Platform <citetitle>Security Guide</citetitle>. </para> - </listitem> - <listitem> - <para>The interceptor redirects the user to the CAS login page - <ulink url="http://localhost:8888/cas/login"/> - . The user enters the correct authentication information, and submits the form. -</para> - <para>The CAS server retrieves the information from the identity store. The store could be an external database, a LDAP server, or from information obtained through an authentication plug-in such as the one shipped with JBoss Portal Platform. Refer to <xref linkend="sect-CAS_Authentication_Plug-in"/> for specific details about this technology.</para> - </listitem> - <listitem> - <para> Once CAS determines the user has the correct access privileges to access the portal server, CAS redirects the user back to the portal through another marker URL such as - <ulink url="http://localhost:8080/portal/initiatelogin"/> - . </para> - <para>The <emphasis role="strong">InitiateLoginFilter</emphasis> -interceptor acts on the user redirection to - <emphasis role="italics">/portal/initiatelogin</emphasis> -by obtaining a CAS ticket attached in the HTTP request inside the - <emphasis role="italics">ticket</emphasis> -parameter. The interceptor then delegates validation of this ticket to a configured - <emphasis role="strong">CASAgent</emphasis> - component. </para> - </listitem> - <listitem> - <para>The <emphasis>CASAgent</emphasis> validates the ticket by sending a validation request to the CAS server through a configured back channel. The CAS server validates the request, and ensures it contains the user name of the authenticated user in step 3. + </section> + + <section id="sect-CAS-Logout_Workflow"> + <title>Logout Process</title> + + <para> + The logout process with CAS integration occurs in the following order: </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>The <emphasis role="strong">SSOLoginModule</emphasis> detects whether the user has been successfully validated by - <emphasis role="italics">CASAgent</emphasis>. If this is the case, the login module obtains data about user (groups, memberships) from - <emphasis role="italics">OrganizationService</emphasis> - and encapsulates the details into an - <emphasis role="strong">Identity</emphasis> - object. </para> - </listitem> - <listitem> - <para>The - <emphasis role="strong">JBossAS7LoginModule</emphasis> completes the authentication request by establishing the JAAS - <emphasis role="italics">Subject</emphasis>, - and saves the - <emphasis role="italics">Identity</emphasis> - object to the - <emphasis role="italics">IdentityRegistry</emphasis>. For more information about login modules, refer to <xref linkend="sect-Authentication_Authorization_Intro-Login_Modules"/>. -</para> - </listitem> - <listitem> - <para>After successful JAAS authentication, the user is redirected to the portal in an authenticated state.</para> - </listitem> - </orderedlist> - <para>For more information about the available Login Modules shipped with the product, refer to the JBoss Enterprise Application Platform <citetitle>Security Guide</citetitle>. </para> - </section> - <section id="sect-CAS-Logout_Workflow"> - <title>Logout Process</title> - <para>The logout process with CAS integration occurs in the following order:</para> - <orderedlist> - <listitem> - <para>The authenticated user clicks the - <emphasis role="italics">Sign out</emphasis> - link. + + <orderedlist> + <listitem> + <para> + The authenticated user clicks the <emphasis role="italics">Sign out</emphasis> link. + </para> + </listitem> + + <listitem> + <para> + The <emphasis role="strong">CASLogoutFilter</emphasis> interceptor recognizes the logout request, and redirects the user to the CAS logout page <ulink url="http://localhost:8888/cas/logout"/> . + </para> + </listitem> + + <listitem> + <para> + The CAS server logs out the user, and invalidate the CAS cookie <emphasis role="italics">CASTGC</emphasis> . + </para> + </listitem> + + <listitem> + <para> + CAS redirects the user back to the portal using the logout redirection configured in <xref linkend="sect-CAS_Logout_Redirection"/> . + </para> + + <para> + If the <emphasis role="italics">CASLogoutFilter</emphasis> is enabled, the user is logged out from both the portal and CAS server. + </para> + </listitem> + + <listitem> + <para> + 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> + For scope purposes, the setup instructions assume the following configuration outcomes: </para> - </listitem> - <listitem> - <para>The - <emphasis role="strong">CASLogoutFilter</emphasis> -interceptor recognizes the logout request, and redirects the user to the CAS logout page - <ulink url="http://localhost:8888/cas/logout"/> -. </para> - </listitem> - <listitem> - <para>The - CAS server logs out the user, and invalidate the CAS cookie - <emphasis role="italics">CASTGC</emphasis> . </para> - </listitem> - <listitem> - <para>CAS redirects the user back to the portal using the logout redirection configured in <xref linkend="sect-CAS_Logout_Redirection"/> . + + <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> + Once configured, Apache Maven is used to create the custom CAS web archive, suitable for deployment. + </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> + Apache Tomcat is configured to listen on <emphasis role="italics">localhost:8888</emphasis>. + </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> + 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> + 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> + 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> - <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> -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>For scope purposes, the setup instructions assume the following configuration outcomes: </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>Once configured, Apache Maven is used to create the custom CAS web archive, suitable for deployment.</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>Apache Tomcat is configured to listen on <emphasis role="italics">localhost:8888</emphasis>.</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> - 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> - 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>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>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>CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS <literal>AuthenticationPlugin</literal>. </para> - <para>Implementing the <literal>AuthenticationPlugin</literal> on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the <literal>AuthenticationPlugin</literal>. </para> - <para>The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal&apos;s own identity storage provided by the PicketLink IDM - <emphasis role="italics">OrganizationService</emphasis>. The <literal>AuthenticationPlugin</literal> receives the portal&apos;s response to the CAS server, and continues with the authentication process based on user data in the response. -</para> - <para>For the plug-in to function correctly, it must be properly configured on the CAS server to connect to this service. Set up the server to authenticate against the portal using the REST call-back.</para> - <procedure> - <title>Configuring the Authentication plug-in</title> - <step> - <para> - Open - <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</code> - . - </para> - </step> - <step> - <para>Replace the default configuration, which declares the Jasig <classname>SimpleTestUsernamePasswordAuthenticationHandler</classname> Authentication Handler with the following supported Authentication Handler. </para> - <note> - <para>This configuration is available in the - <code><replaceable>PORTAL_SSO</replaceable>/cas.war/WEB-INF/deployerConfigContext.xml</code>. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. </para> - </note> - <programlisting> + + <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> + CAS can be configured to make secure authentication callbacks to a RESTful service installed on the remote portal instance using the supplied CAS <literal>AuthenticationPlugin</literal>. + </para> + + <para> + Implementing the <literal>AuthenticationPlugin</literal> on the CAS server has the advantage of leveraging a single identity storage for portal user, group and role data. If a new user is added using the portal user management interface, the user information is instantly accessible to the CAS server through the technology implemented by the <literal>AuthenticationPlugin</literal>. + </para> + + <para> + The plug-in verifies user credentials by connecting to an existing portal instance using REST over the HTTP protocol. The portal serves a REST authentication callback request, and verifies the user identity against the portal&apos;s own identity storage provided by the PicketLink IDM <emphasis role="italics">OrganizationService</emphasis>. The <literal>AuthenticationPlugin</literal> receives the portal&apos;s response to the CAS server, and continues with the authentication process based on user data in the response. + </para> + + <para> + For the plug-in to function correctly, it must be properly configured on the CAS server to connect to this service. Set up the server to authenticate against the portal using the REST call-back. + </para> + + <procedure> + <title>Configuring the Authentication plug-in</title> + + <step> + <para> + Open <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/deployerConfigContext.xml</code> . + </para> + </step> + + <step> + <para> + Replace the default configuration, which declares the Jasig <classname>SimpleTestUsernamePasswordAuthenticationHandler</classname> Authentication Handler with the following supported Authentication Handler. + </para> + + <note> + <para> + This configuration is available in the <code><replaceable>PORTAL_SSO</replaceable>/cas.war/WEB-INF/deployerConfigContext.xml</code>. If you choose to take this configuration file, ensure the default host, port and context parameters are adjusted to match the values corresponding to the remote portal instance. + </para> + </note> +<programlisting> &lt;!-- XML comment used for configuration guidance removed for ease of readability+--&gt; &lt;bean class=&quot;org.gatein.sso.cas.plugin.AuthenticationPlugin&quot;&gt; @@ -252,122 +319,189 @@ &lt;property name=&quot;httpMethod&quot;&gt;&lt;value&gt;POST&lt;/value&gt;&lt;/property&gt; &lt;/bean&gt; </programlisting> - </step> - <step> - <para> - Copy all jars from - <code>PORTAL_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>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; + </step> + + <step> + <para> + Copy all jars from <code>PORTAL_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> + The CAS server displays the CAS logout page with a link to return to the portal by default. To make the CAS server redirect to the portal page after a logout, modify <code>CAS_DIR/cas-server-webapp/src/main/webapp/</code> <code>WEB-INF/cas-servlet.xml</code> to include the <code>followServiceRedirects=&quot;true&quot;</code> parameter: + </para> +<programlisting language="">&lt;bean id=&quot;logoutController&quot; class=&quot;org.jasig.cas.web.LogoutController&quot; p:centralAuthenticationService-ref=&quot;centralAuthenticationService&quot; p:logoutView=&quot;casLogoutView&quot; p:warnCookieGenerator-ref=&quot;warnCookieGenerator&quot; p:ticketGrantingTicketCookieGenerator-ref=&quot;ticketGrantingTicketCookieGenerator&quot; p:followServiceRedirects=&quot;true&quot;/&gt; </programlisting> - </section> - <section id="sect-CAS_SSO_Cookie_Configuration"> - <title>CAS SSO cookie configuration (CASTGC)</title> - <para>Jasic CAS uses a cookie named <firstterm>CAS Ticket Granting Cookie</firstterm> - (CASTGC) -to control the authentication state within the browser session. The cookie contains a Ticket Granting Ticket (TGT), which preserves SSO authentication where more than one site is controlled by the same SSO profile. </para> - <example id="exam-CASTGC_Authentication"> - <title>Basic CASTGC Portal Authentication Scenario </title> - <para>Two portal servers are provisioned that use a single CAS server to manage authentication. The portals are named <literal>accounts</literal> and <literal>services</literal>.</para> - <para>When a user initially accesses the <literal>accounts</literal> portal, they provide their SSO credentials, and CAS authenticates them as a registered user. The user then switches to the <literal>services</literal> portal, and is authenticated when she clicks the Sign in link. </para> - <para>This behavior is correct given this example because the browser instance stores the browser authentication state using the CASTCG cookie. The CASTCG cookie in this instance creates new ticket for the <literal>services</literal> portal automatically based on the authentication state present for the accounts portal. - </para> - </example> - <para>The behavior described in <xref linkend="exam-CASTGC_Authentication"/>exists through a secured connection only (https connection). To benefit from authentication across two or more portals, one of the options below must be implemented. Choose the correct option based on the deployment environment: </para> - <variablelist> - <varlistentry> - <term>Testing</term> - <listitem> - <para>Alter the CASTGC cookie to be non-secure. </para> - <para>The cookie can be accessed through http (insecure) connections. </para> - <para>To configure this test behavior, open - <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml</code> - and switch the attribute - <code>cookieSecure</code> - to false. </para> - <programlisting>&lt;bean id=&quot;ticketGrantingTicketCookieGenerator&quot; + </section> + + <section id="sect-CAS_SSO_Cookie_Configuration"> + <title>CAS SSO cookie configuration (CASTGC)</title> + + <para> + Jasic CAS uses a cookie named + <firstterm> + CAS Ticket Granting Cookie + </firstterm> + (CASTGC) to control the authentication state within the browser session. The cookie contains a Ticket Granting Ticket (TGT), which preserves SSO authentication where more than one site is controlled by the same SSO profile. + </para> + + <example id="exam-CASTGC_Authentication"> + <title>Basic CASTGC Portal Authentication Scenario</title> + + <para> + Two portal servers are provisioned that use a single CAS server to manage authentication. The portals are named <literal>accounts</literal> and <literal>services</literal>. + </para> + + <para> + When a user initially accesses the <literal>accounts</literal> portal, they provide their SSO credentials, and CAS authenticates them as a registered user. The user then switches to the <literal>services</literal> portal, and is authenticated when she clicks the Sign in link. + </para> + + <para> + This behavior is correct given this example because the browser instance stores the browser authentication state using the CASTCG cookie. The CASTCG cookie in this instance creates new ticket for the <literal>services</literal> portal automatically based on the authentication state present for the accounts portal. + </para> + </example> + + <para> + The behavior described in <xref linkend="exam-CASTGC_Authentication"/>exists through a secured connection only (https connection). To benefit from authentication across two or more portals, one of the options below must be implemented. Choose the correct option based on the deployment environment: + </para> + + <variablelist> + <varlistentry> + <term>Testing</term> + + <listitem> + <para> + Alter the CASTGC cookie to be non-secure. + </para> + + <para> + The cookie can be accessed through http (insecure) connections. + </para> + + <para> + To configure this test behavior, open <code>CAS_DIR/cas-server-webapp/src/main/webapp/WEB-INF/spring-configuration/ticketGrantingTicketCookieGenerator.xml</code> and switch the attribute <code>cookieSecure</code> to false. + </para> +<programlisting>&lt;bean id=&quot;ticketGrantingTicketCookieGenerator&quot; p:cookieSecure=&quot;false&quot; p:cookieMaxAge=&quot;-1&quot; p:cookieName=&quot;CASTGC&quot; p:cookiePath=&quot;/cas&quot; /&gt;</programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term>Production</term> - <listitem> - <para>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>Install and configure Apache Tomcat 7, which provides the host server for the CAS server. </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>Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution.</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_DIST</replaceable>.</para> - </step> - <step> - <para>Edit <filename>TOMCAT_DIST/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>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>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>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> - 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>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>The exception to this rule is where configuration present in <filename>security-sso-configuration.xml</filename> is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor). </para> - </section> - <section id="sect-CAS_Configuring_the_Platform"> - <title>Portal configuration.properties for CAS SSO</title> - <para>To prepare the portal platform for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, also needs to be specified. -</para> - <procedure> - <title>Configuring SSO configuration.properties for CAS</title> - <step> - <para>Open <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> and locate the SSO sections in the file.</para> - </step> - <step> - <para>Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter.</para> - <programlisting> + </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> + Install and configure Apache Tomcat 7, which provides the host server for the CAS server. + </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> + Visit <ulink url="http://tomcat.apache.org/download-70.cgi"/> and download the Tomcat 7 binary distribution. + </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_DIST</replaceable>. + </para> + </step> + + <step> + <para> + Edit <filename>TOMCAT_DIST/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> + 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> + 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> + 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> + 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> + 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> + The exception to this rule is where configuration present in <filename>security-sso-configuration.xml</filename> is fundamentally unsuitable for the production environment the server will be deployed to, or when additional underlying functionality is required (for example, another custom interceptor). + </para> + </section> + + <section id="sect-CAS_Configuring_the_Platform"> + <title>Portal configuration.properties for CAS SSO</title> + + <para> + To prepare the portal platform for CAS authentication, SSO filters and login modules need to be specified in global configuration files. The location of the CAS server, as configured in a locally-running Apache Tomcat server, also needs to be specified. + </para> + + <procedure> + <title>Configuring SSO configuration.properties for CAS</title> + + <step> + <para> + Open <filename>JPP_SERVER/standalone/configuration/gatein/configuration.properties</filename> and locate the SSO sections in the file. + </para> + </step> + + <step> + <para> + Make the following changes to the file to declare the correct login module, server and portal URLs, and the logout filter. + </para> +<programlisting> # SSO gatein.sso.enabled=true gatein.sso.callback.enabled=${gatein.sso.enabled} @@ -379,497 +513,649 @@ 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>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. + </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> + Specifies whether the REST callback authentication handler is enabled. + </para> + + <para> + The handler is required if the CAS server must use the SSO Authentication plug-in to handle portal authentication. See <xref linkend="sect-CAS_Logout_Redirection"/> for details. The callback handler is enabled by default. Set the parameter to false if the Authentication Plugin on the CAS server side is not required. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.login.module.enabled</term> + + <listitem> + <para> + Specifies whether a pre-defined SSO login module declared in <filename> JPP_SERVER/standalone/configuration/standalone.xml</filename> is used for authentication. When the property is set to &quot;true&quot;, the SSODelegateLoginModule delegates work to another login module, as specified using the <property>gatein.sso.login.module.class</property> property. SSODelegateLoginModule will also resend all its options to its delegate. + </para> + + <para> + This parameter removes the need to manually change any login module configuration in the standalone.xml file, which simplifies platform configuration. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.login.module.class</term> + + <listitem> + <para> + Specifies the classname of the login module SSODelegateLoginModule will delegate to. This parameter will work only if gatein.sso.login.module.enabled is specified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.server.url</term> + + <listitem> + <para> + Specifies the URL from which the CAS server is accessible. + </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> + Specifies the class of the logout filter. In the example above <code>org.gatein.sso.agent.filter.CASLogoutFilter</code> is the correct choice because this filter is able to redirect to the CAS server and perform logout on CAS side. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.filter.logout.url</term> + + <listitem> + <para> + Specifies the CAS server logout URL, which is used for redirection by the logout filter + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.filter.logout.enabled</term> + + <listitem> + <para> + Optional parameter, which specifies whether the logout interceptor is enabled. To disable logout on CAS side, set the parameter value to &quot; false&quot; . This results in both options <code>gatein.sso.filter.logout.class</code> and <code>gatein.sso.filter.logout.url</code> are ignored + </para> + + <para> + When a user logs out of the portal, the CAS authentication ticket is still valid for other CAS authenticated sites. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>gatein.sso.filter.login.sso.url</term> + + <listitem> + <para> + Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page. + </para> + <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> + <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> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.callback.enabled</term> - <listitem> - <para> -Specifies whether the REST callback authentication handler is enabled. </para> - <para>The handler is required if the CAS server must use the SSO Authentication plug-in to handle portal authentication. See <xref linkend="sect-CAS_Logout_Redirection"/> -for details. The callback handler is enabled by default. Set the parameter to false if the Authentication Plugin on the CAS server side is not required. + + <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> + In a terminal, navigate to <filename>CAS_DIR/cas-server-webapp/</filename>, and run <command>mvn install</command>. + </para> + </step> + + <step> + <para> + Copy <filename>CAS_DIR/cas-server-webapp/target/cas.war</filename> to <filename>TOMCAT_DIST/webapps</filename>. + </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> + 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> + 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> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.login.module.enabled</term> - <listitem> - <para>Specifies whether a pre-defined SSO login module declared in <filename> JPP_SERVER/standalone/configuration/standalone.xml</filename> is used for authentication. When the property is set to &quot;true&quot;, the SSODelegateLoginModule delegates work to another login module, as specified using the <property>gatein.sso.login.module.class</property> property. SSODelegateLoginModule will also resend all its options to its delegate.</para> - <para>This parameter removes the need to manually change any login module configuration in the standalone.xml file, which simplifies platform configuration. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.login.module.class</term> - <listitem> - <para>Specifies the classname of the login module SSODelegateLoginModule will delegate to. This parameter will work only if gatein.sso.login.module.enabled is specified.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.server.url</term> - <listitem> - <para> - Specifies the URL from which the CAS server is accessible. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.portal.url</term> - <listitem> - <para> - Specifies the URL from which the JBoss Portal Platform is accessible. + </section> + </section> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Java_Open_Single_Sign_On_Project"> + <title>Java Open Single Sign-On Project</title> + + <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> + This single sign-on plug-in enables seamless integration between JBoss Portal Platform and the Java Open Single Sign-On (JOSSO) framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"/> . + </para> + + <para> + The procedures in this section detail setting up the JOSSO server to authenticate against the JBoss Portal Platform login module. + </para> + + <para> + After completing all procedures in this section, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. + </para> + + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"> + <title>Download and extract JOSSO server</title> + + <step> + <para> + Download an embedded Apache JOSSO version from <ulink url="http://sourceforge.net/projects/josso/files/JOSSO/" type="http"> http://sourceforge.net/projects/josso/files/ </ulink> . + </para> + + <note> + <para> + Integration with JOSSO versions between 1.8.1 to 1.8.4 is supported. Versions other than these do not offer an embedded Apache instance. + </para> + + <para> + The JOSSO version is referred to as <replaceable>josso-18X</replaceable> in all procedures within this section. + </para> + </note> + </step> + + <step> + <para> + Extract the package to an appropriate directory. This location is referred to as <filename>JOSSO_HOME</filename> in this example. + </para> + </step> + </procedure> + + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> + <title>Configure the JOSSO server</title> + + <step> + <para> + Copy the specified files from <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin</filename> + </para> + + <itemizedlist> + <listitem> + <para> + josso-gateway-config.xml + </para> + </listitem> + + <listitem> + <para> + josso-gateway-gatein-stores.xml + </para> + </listitem> + </itemizedlist> + </step> + + <step> + <para> + Paste the files into the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/lib</filename> directory. + </para> + </step> + + <step> + <para> + Copy <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin/gatein.properties</filename> to the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/classes/</filename> directory + </para> + </step> + + <step> + <para> + Edit the <filename>JOSSO_HOME/conf/server.xml</filename> file and change all ports from 8080 to 8888. This port change prevents a conflict with the default JBoss Portal Platform port. + <note> + <title>Port Conflicts</title> + + <para> + If JBoss Portal Platform is running on the same machine as Apache, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the <literal>admin</literal> port from 8005 to 8805, and the <literal>AJP</literal> port from 8009 to 8809. + </para> + </note> + </para> + </step> + + <step> + <para> + Follow the steps in <xref linkend="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"/> to configure the JOSSO Client. + </para> + </step> + </procedure> + + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> + <title>Configure the JOSSO client</title> + + <note> + <para> + There are some changes in JOSSO agent API between versions 1.8.1 and 1.8.2, which require different modules for different JOSSO versions. This procedure uses <replaceable>josso-18X</replaceable> to substitute the directory <filename>josso-181</filename>, or josso-182 or newer. + </para> + </note> + + <step> + <para> + Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/lib</filename> into <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib</filename>. + </para> + </step> + + <step> + <para> + Copy <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> and paste the file into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/classes</filename> directory. + </para> + </step> + + <step> + <para> + Edit <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Follow the procedure in <xref linkend="proc-Test_the_JOSSO_Installation"/> to verify the login configuration is correct. + </para> + </step> + </procedure> + + <procedure id="proc-Test_the_JOSSO_Installation"> + <title>Test the JOSSO Installation</title> + + <step> + <para> + Start (or restart) JBoss Portal Platform. + </para> + </step> + + <step> + <para> + Start (or restart) the JOSSO Apache instance. + </para> + </step> + + <step> + <para> + Open <ulink url="http://localhost:8888/josso/signon/login.do"/> to display the JOSSO login screen. + </para> + </step> + + <step> + <para> + Login with the user name <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal to verify the configuration to this point is correct. + </para> + </step> + </procedure> + + <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> + <title>Redirect portal authentication to JOSSO</title> + + <para> + Redirect all user authentication to the JOSSO server. Information about where the JOSSO server is hosted must be properly configured within the JBoss Portal Platform instance. </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. + + <step> + <para> + In the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the <guilabel>Sign In</guilabel> link as follows: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Modify the <guilabel>Sign In</guilabel> link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with the following HTML code: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text"/></programlisting> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"> + <title>OpenSSO</title> + + <para> + This section details the setting up of OpenSSO server to authenticate against the JBoss Portal Platform login module. + </para> + + <procedure id="proc-Reference_Guide-OpenSSO-Obtaining_OpenSSO"> + <title>Obtaining OpenSSO</title> + + <step> + <para> + OpenSSO must be purchased from <ulink url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... type="http"> Oracle </ulink> . + </para> + + <para> + For testing purposes, use OpenSSO_80U2, which can be downloaded from <ulink url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... type="http">Oracle </ulink> . + </para> + </step> + + <step> + <para> + Extract the package into a suitable location. This location will be referred to as <filename>OPENSSO_HOME</filename> in this example. + </para> + </step> + </procedure> + + <note> + <para> + It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between JBoss Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration" type="http"> here </ulink> . </para> - </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 + </note> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> + <title>Modifying the OpenSSO server</title> + + <para> + To configure the web server as required, it is simpler to directly modify the source files. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.filter.logout.enabled</term> - <listitem> - <para>Optional parameter, which specifies whether the logout interceptor is enabled. To disable logout on CAS side, set the parameter value to &quot; - false&quot; - . This results in both options - <code>gatein.sso.filter.logout.class</code> - and - <code>gatein.sso.filter.logout.url</code> are ignored </para> - <para>When a user logs out of the portal, the CAS authentication ticket is still valid for other CAS authenticated sites. </para> - </listitem> - </varlistentry> - <varlistentry> - <term>gatein.sso.filter.login.sso.url</term> - <listitem> - <para> - Specifies the CAS server login URL, which is used by LoginRedirectFilter for redirection to the CAS server login page. + + <para> + The first step is to add the JBoss Portal Platform Authentication Plugin. </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> - <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>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>In a terminal, navigate to <filename>CAS_DIR/cas-server-webapp/</filename>, and run <command>mvn install</command>.</para> - </step> - <step> - <para>Copy <filename>CAS_DIR/cas-server-webapp/target/cas.war</filename> to <filename>TOMCAT_DIST/webapps</filename>.</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>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>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>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> - This single sign-on plug-in enables seamless integration between JBoss Portal Platform and the Java Open Single Sign-On (JOSSO) framework. Details about JOSSO can be found at <ulink url="http://www.josso.org"/> . - </para> - <para> The procedures in this section detail setting up the JOSSO server to authenticate against the JBoss Portal Platform login module. - </para> - <para>After completing all procedures in this section, all links redirecting to the user authentication pages will redirect to the JOSSO centralized authentication form. - </para> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-JOSSO_server"> - <title>Download and extract JOSSO server</title> - <step> - <para> - Download an embedded Apache JOSSO version from <ulink url="http://sourceforge.net/projects/josso/files/JOSSO/" type="http"> http://sourceforge.net/projects/josso/files/ </ulink> . - </para> - <note> - <para>Integration with JOSSO versions between 1.8.1 to 1.8.4 is supported. Versions other than these do not offer an embedded Apache instance.</para> - <para>The JOSSO version is referred to as <replaceable>josso-18X</replaceable> in all procedures within this section. </para> - </note> - </step> - <step> - <para> - Extract the package to an appropriate directory. This location is referred to as <filename>JOSSO_HOME</filename> in this example. - </para> - </step> - </procedure> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Modifying_JOSSO_server"> - <title>Configure the JOSSO server</title> - <step> - <para>Copy the specified files from <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin</filename> </para> - <itemizedlist> - <listitem> - <para>josso-gateway-config.xml</para> - </listitem> - <listitem> - <para>josso-gateway-gatein-stores.xml</para> - </listitem> - </itemizedlist> - </step> - <step> - <para>Paste the files into the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/lib</filename> directory.</para> - </step> - <step> - <para>Copy <filename>PORTAL_SSO/josso/<replaceable>josso-18X</replaceable>/plugin/gatein.properties</filename> to the <filename><replaceable>JOSSO_HOME</replaceable>/webapps/josso/WEB-INF/classes/</filename> directory</para> - </step> - <step> - <para> Edit the <filename>JOSSO_HOME/conf/server.xml</filename> file and change all ports from 8080 to 8888. This port change prevents a conflict with the default JBoss Portal Platform port. - <note> - <title>Port Conflicts</title> + <para> - If JBoss Portal Platform is running on the same machine as Apache, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the <literal>admin</literal> port from 8005 to 8805, and the <literal>AJP</literal> port from 8009 to 8809. - </para> - </note> - - </para> - </step> - <step> - <para>Follow the steps in <xref linkend="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"/> to configure the JOSSO Client. </para> - </step> - </procedure> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_JOSSO_client"> - <title> Configure the JOSSO client </title> - <note> - <para> -There are some changes in JOSSO agent API between versions 1.8.1 and 1.8.2, which require different modules for different JOSSO versions. -This procedure uses <replaceable>josso-18X</replaceable> to substitute the directory <filename>josso-181</filename>, or josso-182 or newer. -</para> - </note> - <step> - <para>Copy the library files from <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/lib</filename> into <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib</filename>.</para> - </step> - <step> - <para> - Copy <filename><replaceable>PORTAL_SSO</replaceable>/josso/<replaceable>josso-18X</replaceable>/gatein.ear/portal.war/WEB-INF/classes/josso-agent-config.xml</filename> and paste the file into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/classes</filename> directory. - </para> - </step> - <step> - <para> - Edit <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default111.xml" parse="text"/></programlisting> - </step> - <step> - <para>Follow the procedure in <xref linkend="proc-Test_the_JOSSO_Installation"/> to verify the login configuration is correct. </para> - </step> - </procedure> - <procedure id="proc-Test_the_JOSSO_Installation"> - <title>Test the JOSSO Installation</title> - <step> - <para> - Start (or restart) JBoss Portal Platform. - </para> - </step> - <step> - <para>Start (or restart) the JOSSO Apache instance.</para> - </step> - <step> - <para>Open <ulink url="http://localhost:8888/josso/signon/login.do"/> to display the JOSSO login screen.</para> - </step> - <step> - <para> - Login with the user name <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal to verify the configuration to this point is correct. </para> - </step> - </procedure> - <procedure id="proc-Reference_Guide-Java_Open_Single_Sign_On_Project-Setup_the_portal_to_redirect_to_JOSSO"> - <title>Redirect portal authentication to JOSSO</title> - <para>Redirect all user authentication to the JOSSO server. - Information about where the JOSSO server is hosted must be properly configured within the JBoss Portal Platform instance. - </para> - <step> - <para> - In the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file modify the <guilabel>Sign In</guilabel> link as follows: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default112.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Modify the <guilabel>Sign In</guilabel> link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default113.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with the following HTML code: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default114.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default115.xml" parse="text"/></programlisting> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-OpenSSO"> - <title>OpenSSO</title> - <para> - This section details the setting up of OpenSSO server to authenticate against the JBoss Portal Platform login module. - </para> - <procedure id="proc-Reference_Guide-OpenSSO-Obtaining_OpenSSO"> - <title>Obtaining OpenSSO</title> - <step> - <para> - OpenSSO must be purchased from <ulink url="http://www.oracle.com/technetwork/middleware/id-mgmt/overview/i... type="http"> Oracle </ulink> . - </para> - <para> - For testing purposes, use OpenSSO_80U2, which can be downloaded from <ulink url="http://download.oracle.com/otn/nt/middleware/11g/oracle_opensso... type="http">Oracle </ulink> . - </para> - </step> - <step> - <para> - Extract the package into a suitable location. This location will be referred to as <filename>OPENSSO_HOME</filename> in this example. - </para> - </step> - </procedure> - <note> - <para> - It is also possible to use OpenAM instead of OpenSSO server. OpenAM is free and the integration steps between JBoss Portal Platform and OpenAM are very similar as with OpenSSO. More info is available <ulink url="http://community.jboss.org/wiki/GateInAndOpenAMIntegration" type="http"> here </ulink> . + The plug-in makes secure callbacks to a RESTful service installed on the remote JBoss Portal Platform server to authenticate a user. </para> - </note> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Modifying_the_OpenSSO_server"> - <title>Modifying the OpenSSO server</title> - <para> - To configure the web server as required, it is simpler to directly modify the source files. - </para> - <para> - The first step is to add the JBoss Portal Platform Authentication Plugin. - </para> - <para> - The plug-in makes secure callbacks to a RESTful service installed on the remote JBoss Portal Platform server to authenticate a user. - </para> - <para> - In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. - </para> - <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> - <title>Modifying OpenSSO server</title> - <step> - <para> - Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as <filename>TOMCAT_HOME</filename> in this example. - </para> - </step> - <step> - <para> - Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Portal Platform port. - <note> - <para> - If JBoss Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. + + <para> + In order for the plug-in to function correctly, it needs to be properly configured to connect to this service. This configuration is done via the <filename>opensso.war/config/auth/default/AuthenticationPlugin.xml</filename> file. + </para> + + <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Modifying_OpenSSO_server"> + <title>Modifying OpenSSO server</title> + + <step> + <para> + Obtain a copy of Tomcat and extract it into a suitable location. This location will be referred to as <filename>TOMCAT_HOME</filename> in this example. + </para> + </step> + + <step> + <para> + Edit <filename>TOMCAT_HOME/conf/server.xml</filename> and change the 8080 port to 8888 to avoid a conflict with the default JBoss Portal Platform port. + <note> + <para> + If JBoss Portal Platform is running on the same machine as Tomcat, other ports need to be changed in addition to 8080 in order to avoid port conflicts. They can be changed to any free port. For example, you can change the admin port from 8005 to 8805 and the AJP port from 8009 to 8809. </para> - </note> - - </para> - </step> - <step> - <para> - Ensure the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file matches the following: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Copy the following files into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>: - </para> - <itemizedlist> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<replaceable>VERSION</replaceable>.jar</filename> + </note> + </para> + </step> + + <step> + <para> + Ensure the <filename>TOMCAT_HOME/webapps/opensso/config/auth/default/AuthenticationPlugin.xml</filename> file matches the following: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default117.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Copy the following files into the Tomcat directory at <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/lib</filename>: + </para> + + <itemizedlist> + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/sso-opensso-plugin-<replaceable>VERSION</replaceable>.jar</filename> </para> - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-<replaceable>VERSION</replaceable>.jar</filename> + </listitem> + + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-httpclient-<replaceable>VERSION</replaceable>.jar</filename> </para> - </listitem> - <listitem> - <para> - <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-<replaceable>VERSION</replaceable>.jar</filename> + </listitem> + + <listitem> + <para> + <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/lib/commons-logging-<replaceable>VERSION</replaceable>.jar</filename> </para> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Copy the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/classes/gatein.properties</filename> file into the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> directory. - </para> - </step> - <step> - <para> - Tomcat should start and be able to access <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . - </para> - <mediaobject> - <imageobject role="html"> - <imagedata width="444" align="center" scale="110" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> - </imageobject> - <imageobject role="fo"> - <imagedata width="444" contentwidth="150mm" align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> - </imageobject> - </mediaobject> - <note> - <para> + </listitem> + </itemizedlist> + </step> + + <step> + <para> + Copy the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/plugin/WEB-INF/classes/gatein.properties</filename> file into the <filename>TOMCAT_HOME/webapps/opensso/WEB-INF/classes</filename> directory. + </para> + </step> + + <step> + <para> + Tomcat should start and be able to access <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> . + </para> + + <mediaobject> + <imageobject role="html"> + <imagedata width="444" align="center" scale="110" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> + </imageobject> + + <imageobject role="fo"> + <imagedata width="444" contentwidth="150mm" align="center" fileref="images/AuthenticationAndIdentity/SSO/opensso-shot.png" format="PNG"/> + </imageobject> + </mediaobject> + + <note> + <para> Login will not be available at this point. - </para> - </note> - </step> - </procedure> - <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> - <title>Configure the &quot;gatein&quot; realm</title> - <step> - <para> - Direct your browser to <ulink url="http://localhost:8888/opensso" type="http"> http://localhost:8888/opensso </ulink> - </para> - </step> - <step> - <para> - Create a default configuration. - </para> - </step> - <step> - <para> - Login as <literal>amadmin</literal>. - </para> - <important> - <para> - Go to <menuchoice> - <guimenu>Configuration</guimenu> - <guimenuitem> Authentication </guimenuitem> - </menuchoice> and follow the link to <guilabel>Core</guilabel> - </para> - <para> + </para> + </note> + </step> + </procedure> + + <procedure id="proc-Reference_Guide-Modifying_the_OpenSSO_server-Configure_the_gatein_realm"> + <title>Configure the &quot;gatein&quot; realm</title> + + <step> + <para> + Direct your browser to <ulink url="http://localhost:8888/opensso" type="http"> http://localhost:8888/opensso </ulink> + </para> + </step> + + <step> + <para> + Create a default configuration. + </para> + </step> + + <step> + <para> + Login as <literal>amadmin</literal>. + </para> + + <important> + <para> + Go to <menuchoice> <guimenu>Configuration</guimenu> <guimenuitem> Authentication </guimenuitem> </menuchoice> and follow the link to <guilabel>Core</guilabel> + </para> + + <para> Add a new value with the class name <literal>org.gatein.sso.opensso.plugin.AuthenticationPlugin</literal>. - </para> - <para> + </para> + + <para> If this is not done <literal>AuthenticationPlugin</literal> is not available among other OpenSSO authentication modules. - </para> - </important> - </step> - <step> - <para> - Go to the <guilabel>Access control</guilabel> tab and create new realm called <literal>gatein</literal>. - </para> - </step> - <step> - <substeps> - <step> - <para> - Go to the new <literal>gatein</literal> realm and click on the <guilabel>Authentication</guilabel> tab. + </para> + </important> + </step> + + <step> + <para> + Go to the <guilabel>Access control</guilabel> tab and create new realm called <literal>gatein</literal>. + </para> + </step> + + <step> + <substeps> + <step> + <para> + Go to the new <literal>gatein</literal> realm and click on the <guilabel>Authentication</guilabel> tab. </para> - </step> - <step> - <para> - Click on <guilabel>LDAPService</guilabel> (at the bottom in the <guilabel>Authentication chaining</guilabel> section). + </step> + + <step> + <para> + Click on <guilabel>LDAPService</guilabel> (at the bottom in the <guilabel>Authentication chaining</guilabel> section). </para> - </step> - <step> - <para> - Change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. + </step> + + <step> + <para> + Change the selection from <literal>Datastore</literal>, which is the default module in the authentication chain, to <literal>AuthenticationPlugin</literal>. </para> - </step> - </substeps> - <para> - These changes enable authentication of the <literal>gatein</literal> realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. - </para> - </step> - <step> - <para> - Go to <guilabel>Advanced properties</guilabel> and change <literal>UserProfile</literal> from <parameter>Required</parameter> to <parameter>Dynamic</parameter> to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. - </para> - </step> - <step> - <para> - Increase the user privileges to allow REST access with the following procedure: - </para> - <substeps> - <step> - <para> - Go to <menuchoice> - <guimenu>Access control</guimenu> - <guimenuitem> Top level realm </guimenuitem> - <guimenuitem> Privileges </guimenuitem> - <guimenuitem> All authenticated users </guimenuitem> - </menuchoice>. + </step> + </substeps> + + <para> + These changes enable authentication of the <literal>gatein</literal> realm using the <literal>GateIn REST</literal> service instead of the OpenSSO LDAP server. + </para> + </step> + + <step> + <para> + Go to <guilabel>Advanced properties</guilabel> and change <literal>UserProfile</literal> from <parameter>Required</parameter> to <parameter>Dynamic</parameter> to ensure all new users are automatically created in the OpenSSO datastore after successful authentication. + </para> + </step> + + <step> + <para> + Increase the user privileges to allow REST access with the following procedure: + </para> + + <substeps> + <step> + <para> + Go to <menuchoice> <guimenu>Access control</guimenu> <guimenuitem> Top level realm </guimenuitem> <guimenuitem> Privileges </guimenuitem> <guimenuitem> All authenticated users </guimenuitem> </menuchoice>. </para> - </step> - <step> - <para> - Check the last two checkboxes: + </step> + + <step> + <para> + Check the last two checkboxes: </para> - <itemizedlist> - <listitem> + + <itemizedlist> + <listitem> + <para> + Read and write access only for policy properties + </para> + </listitem> + + <listitem> + <para> + Read and write access to all realm and policy properties + </para> + </listitem> + </itemizedlist> + </step> + </substeps> + </step> + + <step> <para> - Read and write access only for policy properties - </para> - </listitem> - <listitem> + Repeat step 7 for the &apos;<literal>gatein</literal>&apos; realm as well. + </para> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> + <title>Setup the OpenSSO Client</title> + + <procedure id="proc-Reference_Guide-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> + <title>Setup the OpenSSO client</title> + + <step> <para> - Read and write access to all realm and policy properties - </para> - </listitem> - </itemizedlist> - </step> - </substeps> - </step> - <step> - <para> - Repeat step 7 for the &apos;<literal>gatein</literal>&apos; realm as well. - </para> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_OpenSSO_Client"> - <title>Setup the OpenSSO Client</title> - <procedure id="proc-Reference_Guide-Setup_the_OpenSSO_Client-Setup_the_OpenSSO_client"> - <title>Setup the OpenSSO client</title> - <step> - <para> - Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/default/deploy/gatein.ear/lib</filename> directory. - </para> - <para> - Alternatively, in a Tomcat environment, copy the libraries into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/ibib</filename> directory. - </para> - </step> - <step> - <para> - Edit the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text"/></programlisting> - </step> + Copy all libraries from the <filename><replaceable>PORTAL_SSO</replaceable>/opensso/gatein.ear/lib</filename> directory into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/default/deploy/gatein.ear/lib</filename> directory. + </para> + + <para> + Alternatively, in a Tomcat environment, copy the libraries into the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/ibib</filename> directory. + </para> + </step> + + <step> + <para> + Edit the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> and uncomment this section: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default118.xml" parse="text"/></programlisting> + </step> <!-- Removed as per https://issues.jboss.org/browse/JBEPP-1350 <step> <para> @@ -881,154 +1167,185 @@ realmName=gatein-domain; </programlisting> </step> - --> <step> - <para> - Test the installation: - </para> - <procedure> + --> + <step> + <para> + Test the installation: + </para> + + <procedure> + <step> + <para> + Access JBoss Portal Platform by going to <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). + </para> + </step> + + <step> + <para> + Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. + </para> + </step> + </procedure> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + + <para> + The next part of the process is to redirect all user authentication to the OpenSSO server. + </para> + + <para> + Information about where the OpenSSO server is hosted must be properly configured within the JBoss Portal Platform instance. The required configuration is done by modifying three files: + </para> + + <procedure id="proc-Reference_Guide-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> + <title>Setup the portal to redirect to OpenSSO</title> + + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text"/></programlisting> + </step> + </procedure> + + <para> + From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form. + </para> + </section> + </section> + + <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> + <title>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)</title> + + <para> + The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. + </para> + + <para> + For illustrative purposes; a typical use case would be: + </para> + + <procedure> <step> - <para> - Access JBoss Portal Platform by going to <ulink url="http://localhost:8888/opensso/UI/Login?realm=gatein" type="http"> http://localhost:8888/opensso/UI/Login?realm=gatein </ulink> (assuming that the OpenSSO server using Tomcat is still running). - </para> + <para> + A user logs into their desktop computer with a login that is governed by an Active Directory domain. + </para> </step> + <step> - <para> - Login with the username <literal>root</literal> and the password <literal>gtn</literal> or any account created through the portal. - </para> + <para> + The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Portal Platform. + </para> </step> - </procedure> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <para> - The next part of the process is to redirect all user authentication to the OpenSSO server. - </para> - <para> - Information about where the OpenSSO server is hosted must be properly configured within the JBoss Portal Platform instance. The required configuration is done by modifying three files: - </para> - <procedure id="proc-Reference_Guide-Setup_the_portal_to_redirect_to_OpenSSO-Setup_the_portal_to_redirect_to_OpenSSO"> - <title>Setup the portal to redirect to OpenSSO</title> - <step> - <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtml</filename> file as follows: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default119.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Modify the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in the <filename>gatein.ear/web.war/groovy/portal/webui/component/UILogoPortlet.gtmpl</filename> file as follows: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default120.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Replace the entire contents of <filename>gatein.ear/02portal.war/login/jsp/login.jsp</filename> with: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default121.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Add the following Filters to the top of the filter chain in <filename>gatein.ear/02portal.war/WEB-INF/web.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default122.xml" parse="text"/></programlisting> - </step> - </procedure> - <para> - From now on, all links redirecting to the user authentication pages will redirect to the OpenSSO centralized authentication form. - </para> - </section> - </section> - <section id="sect-Reference_Guide-SSO_Single_Sign_On_-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism"> - <title>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)</title> - <para> - The Simple and Protected GSSAPI Negotiation Mechanism (<emphasis role="bold">SPNEGO</emphasis>) uses desktop credentials provided during a desktop login to transparently authenticate a portal user through a web browser. - </para> - <para> - For illustrative purposes; a typical use case would be: - </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> - The user then launches a web browser to access a web application (that uses JBoss Negotiation) hosted on JBoss Portal Platform. - </para> - </step> - <step> - <para> - The browser transfers the desktop credentials to the web application. - </para> - </step> - <step> - <para> - JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the Kerberos ticket from user. - </para> - </step> - <step> - <para> - The user experiences a seamless single sign-on (SSO) into the web application. - </para> - </step> - </procedure> - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> - <title>SPNEGO Server Configuration</title> - <para> - In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against JBoss Portal Platform. + + <step> + <para> + The browser transfers the desktop credentials to the web application. + </para> + </step> + + <step> + <para> + JBoss EAP/AS uses background GSS messages with the Active Directory (or any Kerberos Server) to validate the Kerberos ticket from user. + </para> + </step> + + <step> + <para> + The user experiences a seamless single sign-on (SSO) into the web application. + </para> + </step> + </procedure> + + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration"> + <title>SPNEGO Server Configuration</title> + + <para> + In this section, we will describe some necessary steps for setup Kerberos server on Linux. This server will then be used for SPNEGO authentication against JBoss Portal Platform. </para> - <note> - <title>SPNEGO Basics</title> - <para> - The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"/> to see how to integrate SPNEGO with JBoss Portal Platform. - </para> - <para> - Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment. - </para> - </note> - <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> - <title>SPNEGO Basics</title> - <step> - <para> - Correct the setup of network on the machine. For example, if you are using the &quot;server.local.network&quot; domain as your machine where Kerberos and JBoss Portal Platform are localed, add the line containing the machine&apos;s IP address to the <emphasis role="bold">/etc/host </emphasis> file. - </para> - <programlisting> + + <note> + <title>SPNEGO Basics</title> + + <para> + The procedure below only describes the basic steps to configure the SPNEGO server in a Linux environment. If you are already familiar with SPNEGO, or if you are using Windows and Active Directory domain, you can jump to the <xref linkend="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"/> to see how to integrate SPNEGO with JBoss Portal Platform. + </para> + + <para> + Please note that Kerberos setup is also dependent on your Linux distribution and so steps can be slightly different in your environment. + </para> + </note> + + <procedure id="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"> + <title>SPNEGO Basics</title> + + <step> + <para> + Correct the setup of network on the machine. For example, if you are using the &quot;server.local.network&quot; domain as your machine where Kerberos and JBoss Portal Platform are localed, add the line containing the machine&apos;s IP address to the <emphasis role="bold">/etc/host </emphasis> file. + </para> +<programlisting> 192.168.1.88 server.local.network </programlisting> - <note> - <para> - It is not recommended you use loopback addresses. + <note> + <para> + It is not recommended you use loopback addresses. + </para> + </note> + </step> + + <step> + <para> + Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server. + </para> + </step> + + <step> + <para> + Edit the Kerberos configuration file at <emphasis role="bold">/etc/krb5.config</emphasis>, including: + </para> + + <itemizedlist> + <listitem> + <para> + Uncomment on these lines: </para> - </note> - </step> - <step> - <para> - Install Kerberos with these packages: krb5-admin-server, krb5-kdc, krb5-config, krb5-user, krb5-clients, and krb5-rsh-server. - </para> - </step> - <step> - <para> - Edit the Kerberos configuration file at <emphasis role="bold">/etc/krb5.config</emphasis>, including: - </para> - <itemizedlist> - <listitem> - <para> - Uncomment on these lines: - </para> - <programlisting> +<programlisting> default_tgs_enctypes = des3-hmac-sha1 default_tkt_enctypes = des3-hmac-sha1 permitted_enctypes = des3-hmac-sha1 </programlisting> - </listitem> - <listitem> - <para> - Add <emphasis role="bold">local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like: - </para> - <programlisting> + </listitem> + + <listitem> + <para> + Add <emphasis role="bold">local.network</emphasis> as a default realm and it is also added to the list of realms and remove the remains of realms. The content looks like: + </para> +<programlisting> [libdefaults] default_realm = LOCAL.NETWORK @@ -1081,14 +1398,15 @@ krb4_convert = true krb4_get_tickets = false </programlisting> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Edit the KDC configuraton file at <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> that looks like. - </para> - <programlisting> + </listitem> + </itemizedlist> + </step> + + <step> + <para> + Edit the KDC configuraton file at <emphasis role="bold">/etc/krb5kdc/kdc.conf</emphasis> that looks like. + </para> +<programlisting> [kdcdefaults] kdc_ports = 750,88 @@ -1110,158 +1428,179 @@ kdc = FILE:/home/gatein/krb5logs/kdc.log admin_server = FILE:/home/gatein/krb5logs/kadmin.log </programlisting> - <itemizedlist> - <listitem> - <para> - Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above. - </para> - </listitem> - <listitem> - <para> - Next, create a KDC database using the following command. - </para> - <programlisting> + <itemizedlist> + <listitem> + <para> + Create krb5kdc and krb5logs directory for Kerberos database as shown in the configuration file above. + </para> + </listitem> + + <listitem> + <para> + Next, create a KDC database using the following command. + </para> +<programlisting> sudo krb5_newrealm </programlisting> - </listitem> - <listitem> - <para> - Start the KDC and Kerberos admin servers using these commands: - </para> - <programlisting> + </listitem> + + <listitem> + <para> + Start the KDC and Kerberos admin servers using these commands: + </para> +<programlisting> sudo /etc/init.d/krb5-kdc restart sudo /etc/init.d/krb-admin-server restart </programlisting> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Add Principals and create Keys. - </para> - <itemizedlist> - <listitem> - <para> - Start an interactive &apos;kadmin&apos; session and create the necessary Principals. - </para> - <programlisting> + </listitem> + </itemizedlist> + </step> + + <step> + <para> + Add Principals and create Keys. + </para> + + <itemizedlist> + <listitem> + <para> + Start an interactive &apos;kadmin&apos; session and create the necessary Principals. + </para> +<programlisting> sudo kadmin.local </programlisting> - </listitem> - <listitem> - <para> - Add the JBoss Portal Platform machine and keytab file that need to be authenticated. - </para> - <programlisting> + </listitem> + + <listitem> + <para> + Add the JBoss Portal Platform machine and keytab file that need to be authenticated. + </para> +<programlisting> addprinc -randkey HTTP/server.local.network(a)LOCAL.NETWORK ktadd HTTP/server.local.network(a)LOCAL.NETWORK </programlisting> - </listitem> - <listitem> - <para> - Add the default JBoss Portal Platform user accounts and enter the password for each created user that will be authenticated. - </para> - <programlisting> + </listitem> + + <listitem> + <para> + Add the default JBoss Portal Platform user accounts and enter the password for each created user that will be authenticated. + </para> +<programlisting> addprinc john addprinc demo addprinc root </programlisting> - </listitem> - </itemizedlist> - </step> - <step> - <para> - Test your changed setup by using the command. - </para> - <programlisting> + </listitem> + </itemizedlist> + </step> + + <step> + <para> + Test your changed setup by using the command. + </para> +<programlisting> kinit -A demo </programlisting> - <itemizedlist> - <listitem> - <para> - If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network&apos;s DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. - </para> - </listitem> - <listitem> - <para> - After successful login to Kerberos, you can see your Kerberos ticket when using this command. - </para> - <programlisting> + <itemizedlist> + <listitem> + <para> + If the setup works well, you are required to enter the password created for this user in Step 5. Without the -A, the kerberos ticket validation involved reverse DNS lookups, which can get very cumbersome to debug if your network&apos;s DNS setup is not great. This is a production level security feature, which is not necessary in this development setup. In production environment, it will be better to avoid -A option. + </para> + </listitem> + + <listitem> + <para> + After successful login to Kerberos, you can see your Kerberos ticket when using this command. + </para> +<programlisting> klist </programlisting> - </listitem> - <listitem> - <para> - If you want to logout and destroy your ticket, use this command. - </para> - <programlisting> + </listitem> + + <listitem> + <para> + If you want to logout and destroy your ticket, use this command. + </para> +<programlisting> kdestroy </programlisting> - </listitem> - </itemizedlist> - </step> - </procedure> - </section> - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> - <title>Clients</title> - <para> - After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by JBoss Portal Platform as follows: + </listitem> + </itemizedlist> + </step> + </procedure> + </section> + + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-SPNEGO_Server_Configuration-Clients"> + <title>Clients</title> + + <para> + After performing all configurations above, you need to enable the <emphasis role="bold">Negotiate authentication </emphasis> of Firefox in client machines so that clients could be authenticated by JBoss Portal Platform as follows: </para> - <procedure> - <step> - <para> - Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. - </para> - </step> - <step> - <para> - Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: - </para> - <programlisting> + + <procedure> + <step> + <para> + Start Firefox, then enter the command: <emphasis role="bold">about:config </emphasis> into the address field. + </para> + </step> + + <step> + <para> + Enter <emphasis role="bold">network.negotiate-auth</emphasis> and set the value as below: + </para> +<programlisting> network.negotiate-auth.allow-proxies = true network.negotiate-auth.delegation-uris = .local.network network.negotiate-auth.gsslib (no-value) network.negotiate-auth.trusted-uris = .local.network network.negotiate-auth.using-native-gsslib = true </programlisting> - </step> - </procedure> - <note> - <para> - Consult documentation of your OS or web browser if using different browser than Firefox. - </para> - </note> - </section> - <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> - <title>JBoss Portal Platform Configuration</title> - <para> -JBoss Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO for the portal. Here are the steps to integrate SPNEGO with JBoss Portal Platform. + </step> + </procedure> + + <note> + <para> + Consult documentation of your OS or web browser if using different browser than Firefox. + </para> + </note> + </section> + + <section id="sect-Reference_Guide-SPNEGO_Simple_and_Protected_GSSAPI_Negotiation_Mechanism-JBoss_Enterprise_Portal_Platform_Configuration"> + <title>JBoss Portal Platform Configuration</title> + + <para> + JBoss Portal Platform uses JBoss Negotiation to enable SPNEGO-based desktop SSO for the portal. Here are the steps to integrate SPNEGO with JBoss Portal Platform. </para> - <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> - <title>Advanced SPNEGO Configuration</title> - <step> - <para> - Activate the Host authentication. Add the following host login module to the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename>: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text"/></programlisting> - <para> - The &apos;<literal>keyTab</literal>&apos; value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"/> for more details. - </para> - </step> - <step> - <para> - Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a &apos;<literal>SPNEGO</literal>&apos; authenticators property - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Add the SSO module binaries by copying <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-agent.jar</filename> to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. - </para> - <para> - Copy the <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-spnego.jar</filename> file to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/lib</filename> directory. - </para> - </step> + + <procedure id="proc-Reference_Guide-JBoss_Enterprise_Portal_Platform_Configuration-Advanced_SPNEGO_Configuration"> + <title>Advanced SPNEGO Configuration</title> + + <step> + <para> + Activate the Host authentication. Add the following host login module to the <filename>jboss-as/server/<replaceable>PROFILE</replaceable>/conf/login-config.xml</filename>: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default124.xml" parse="text"/></programlisting> + <para> + The &apos;<literal>keyTab</literal>&apos; value should point to the keytab file that was generated by the <literal>kadmin</literal> Kerberos tool. When using Kerberos on Linux, it should be value of parameter <emphasis role="bold">admin_keytab</emphasis> from kdc.conf file. See the <xref linkend="proc-Reference_Guide-SPNEGO_Server_Configuration-SPNEGO_Basics"/> for more details. + </para> + </step> + + <step> + <para> + Extend the core authentication mechanisms to support SPNEGO. Under <filename>deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml</filename>, add a &apos;<literal>SPNEGO</literal>&apos; authenticators property + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default125.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Add the SSO module binaries by copying <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-agent.jar</filename> to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/lib/</filename> directory. + </para> + + <para> + Copy the <filename>PORTAL_SSO/spnego/gatein.ear/lib/sso-spnego.jar</filename> file to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/lib</filename> directory. + </para> + </step> <!-- This step not required as EPP already has the correct version of Negotiation 2.0.4.GA <step> <para> @@ -1270,36 +1609,42 @@ and copy this file to <filename>JBOSS_HOME/server/default/lib</filename> directory as well. </para> </step> - --> <step> - <para> - Modify the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text"/></programlisting> - <para> - This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain. - </para> - </step> - <step> - <para> - Modify <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text"/></programlisting> - <para> - This integrates SPNEGO support into the Portal web archive by switching the authentication mechanism from the default &quot;FORM&quot;-based to &quot;SPNEGO&quot;-based authentication. - </para> - <para> - You can see that the SPNEGO portion also contains the element <code>form-login-config</code>, which is required if you want to enable a fallback to FORM based authentication function. - </para> - <para> - In this case, the portal will attempt to authenticate the user with their Kerberos ticket through SPNEGO. If the user does not have a Kerberos ticket, they will be redirected to FORM authentication and via the login screen. - </para> - <para> - This configuration ensures the first authentication attempt is though SPNEGO and, if this attempt is unsuccessful, another attempt is made using the FORM method. This could occur if the user does not have a valid Kerberos ticket or if the web browser in use does not support SPNEGO authentication with the Kerberos server. - </para> - <para> - If the fallback to FORM function is not required, the <code>form-login-config</code> configuration can be disabled like so: - </para> - <programlisting language="XML" role="XML"><![CDATA[<login-config> + --> + <step> + <para> + Modify the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/META-INF/gatein-jboss-beans.xml</filename> file to match the following: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default126.xml" parse="text"/></programlisting> + <para> + This activates SPNEGO LoginModules with fallback to FORM authentication. When SPNEGO is not available and it needs to fallback to FORM, it will use <emphasis role="bold">gatein-form-auth-domain</emphasis> security domain. + </para> + </step> + + <step> + <para> + Modify <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> to match: + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default127.xml" parse="text"/></programlisting> + <para> + This integrates SPNEGO support into the Portal web archive by switching the authentication mechanism from the default &quot;FORM&quot;-based to &quot;SPNEGO&quot;-based authentication. + </para> + + <para> + You can see that the SPNEGO portion also contains the element <code>form-login-config</code>, which is required if you want to enable a fallback to FORM based authentication function. + </para> + + <para> + In this case, the portal will attempt to authenticate the user with their Kerberos ticket through SPNEGO. If the user does not have a Kerberos ticket, they will be redirected to FORM authentication and via the login screen. + </para> + + <para> + This configuration ensures the first authentication attempt is though SPNEGO and, if this attempt is unsuccessful, another attempt is made using the FORM method. This could occur if the user does not have a valid Kerberos ticket or if the web browser in use does not support SPNEGO authentication with the Kerberos server. + </para> + + <para> + If the fallback to FORM function is not required, the <code>form-login-config</code> configuration can be disabled like so: + </para> +<programlisting language="XML" role="XML"><![CDATA[<login-config> <auth-method>SPNEGO</auth-method> <realm-name>SPNEGO</realm-name> <!-- <form-login-config> @@ -1309,52 +1654,60 @@ --> </login-config> ]]></programlisting> - <para> - In this case the user needs to authenticate through SPNEGO and if that fails, the user will receive an authentication error with HTTP code <literal>401</literal>. The FORM fallback will not be offered. - </para> - </step> - <step> - <para> - Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain. - </para> - <programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text"/></programlisting> - </step> - <step> - <para> - Edit the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: - </para> - <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default129.java" parse="text"/></programlisting> - </step> - <step> - <para> - Start the JBoss Portal Platform; - </para> - <programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default130.java" parse="text"/></programlisting> - <note> - <title>Note</title> + <para> + In this case the user needs to authenticate through SPNEGO and if that fails, the user will receive an authentication error with HTTP code <literal>401</literal>. The FORM fallback will not be offered. + </para> + </step> + + <step> + <para> + Integrate the request pre-processing needed for SPNEGO via filters by adding the following filters to the <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> at the top of the Filter chain. + </para> +<programlisting language="XML" role="XML"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default128.xml" parse="text"/></programlisting> + </step> + + <step> + <para> + Edit the &apos;<emphasis role="bold">Sign In</emphasis>&apos; link in <filename><replaceable>JPP_DIST</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/deploy/gatein.ear/web.war/groovy/groovy/webui/component/UIBannerPortlet.gtmpl</filename> to match the following: + </para> +<programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default129.java" parse="text"/></programlisting> + </step> + + <step> + <para> + Start the JBoss Portal Platform; + </para> +<programlisting language="Java" role="Java"><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../extras/Authentication_Identity_SSO/default130.java" parse="text"/></programlisting> + <note> + <title>Note</title> + + <para> + The <replaceable>PROFILE</replaceable> parameter in the above command should be replaced with the server profile modified with the above configuration. + </para> + </note> + </step> + + <step> + <para> + Login to Kerberos: + </para> +<programlisting>kinit -A demo +</programlisting> + </step> + </procedure> + <para> - The <replaceable>PROFILE</replaceable> parameter in the above command should be replaced with the server profile modified with the above configuration. - </para> - </note> - </step> - <step> - <para> - Login to Kerberos: - </para> - <programlisting>kinit -A demo -</programlisting> - </step> - </procedure> - <para> - Clicking the &apos;Sign In&apos; link on the JBoss Portal Platform should automatically sign the &apos;demo&apos; user into the portal. + Clicking the &apos;Sign In&apos; link on the JBoss Portal Platform should automatically sign the &apos;demo&apos; user into the portal. </para> - <para> - If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Portal Platform because you do not have active Kerberos ticket. You can login with predefined account and password &quot;demo&quot;/&quot;gtn&quot; . + + <para> + If you destroy your kerberos ticket with command <command>kdestroy</command>, then try to login again, you will directed to the login screen of JBoss Portal Platform because you do not have active Kerberos ticket. You can login with predefined account and password &quot;demo&quot;/&quot;gtn&quot; . </para> - </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) @@ -1364,102 +1717,118 @@ 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> - The JBoss SSO valve is enabled by default. The enablement is ensured by the following JBoss Web subsystem configuration entry in the <filename>JPP_DIST/standalone/configuration/standalon-ha.xml</filename> file: - </para> + </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_DIST/standalone/configuration/standalon-ha.xml</filename> file: + </para> <programlisting language="XML"><![CDATA[ <sso cache-container="web" cache-name="sso" reauthenticate="false" /> ]]></programlisting> - <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> - 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> + <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> + 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[ <sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/> ]]></programlisting> - <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> - 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> - 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> + <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> + 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> + 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> 127.0.1.1 machine1.yourdomain.com 127.0.1.2 machine2.yourdomain.com </programlisting> - </step> - <step> - <para> - On both servers, open the <filename><replaceable>JPP_DIST</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> + </step> + + <step> + <para> + On both servers, open the <filename><replaceable>JPP_DIST</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[ <sso cache-container="web" cache-name="sso" reauthenticate="false" domain="yourdomain.com"/> -]]></programlisting> - </step> - <step> - <para> - Start the first server using the following command: - </para> +]]></programlisting> + </step> + + <step> + <para> + Start the first server using the following command: + </para> <programlisting> ./standalone.sh -b machine1.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node1 </programlisting> - </step> - <step> - <para> - Start the second server using the following command: - </para> + </step> + + <step> + <para> + Start the second server using the following command: + </para> <programlisting> ./standalone.sh -b machine2.yourdomain.com -c standalone-ha.xml -Djboss.node.name=node2 </programlisting> - </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> - 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> - 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> - 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> - 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> + </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> + 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> + 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> + 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> + 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[ <sso cache-container="web" cache-name="sso" reauthenticate="true" /> -]]></programlisting> - <para> - The <literal>true</literal> value ensures that reauthentication with user credentials will be performed against the web application'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> +]]></programlisting> + <para> + The <literal>true</literal> value ensures that reauthentication with user credentials will be performed against the web application'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>